Comprehensive Architecture Plan: Full Stack with Hero Integration #8

New issue

Closed

opened 2026-02-09 21:02:55 +00:00 by mik-tf · 1 comment

mik-tf commented

2026-02-09 21:02:55 +00:00

Owner

Overview

Create a comprehensive architecture document that maps the entire Mycelium Marketplace stack and its integration with the Hero ecosystem. This serves as the master reference for all subsequent development work.

Current State

Marketplace Application

Framework: Rust / Actix-Web 4 with Tera templates
Frontend: Bootstrap 5, vanilla JS, responsive (6 breakpoints)
Database: PostgreSQL (available but underutilized)
Reverse Proxy: Caddy with automatic HTTPS
Deployment: Docker Compose with overlay files, OpenTofu for TFGrid VMs

Service Architecture

The marketplace uses a trait-based dependency injection pattern with 12 service traits:

Trait	Fixture Impl	Hero Impl	Status
ProductCatalog	✅	✅	Partially wired
UserAuth	✅	✅	Wired
UserProfile	✅	✅	Partially wired
OrderManager	✅	✅	Not wired in dashboard
CartManager	✅	✅	Wired
WalletManager	✅	✅	Not wired in dashboard
MessagingManager	✅	✅	Partially wired
SSHKeyManager	✅	✅	Wired
ServiceProviderManager	✅	✅	Not wired in dashboard
AppProviderManager	✅	✅	Partially wired
ResourceProviderManager	✅	✅	Partially wired
NodeRentalManager	✅	✅	Wired

Hero Stack Components

Component	Purpose	Integration Status
hero_osis	Schema-first data store (JSON-RPC)	✅ Integrated via OsisClient
hero_ledger	Blockchain/NEAR read-only queries	✅ Integrated for balance queries
hero_index_server	Tantivy full-text search	❌ Not integrated
hero_embedder	Vector embeddings for semantic search	❌ Not integrated
hero_redis	Session/cache persistence	❌ Not integrated
hero_coordinator	Async job orchestration	❌ Not integrated
hero_vault	Secret management	❌ Not integrated
hero_caller	External API gateway	❌ Not integrated
hero_certmanager	TLS certificate management	❌ Not integrated (Caddy handles)

Key Problem: dashboard.rs God-Class

7,810 lines, 44+ handlers in a single file
50+ direct fixture bypasses that ignore ServiceProvider DI
Handlers create their own service instances instead of using injected web::Data<ServiceProvider>
This is the root cause of empty pages when running with hero_osis backend

Target Architecture

┌─────────────────────────────────────────────┐
│              Frontend (Tera + JS)            │
│  Bootstrap 5 │ Responsive │ API-first ready  │
├─────────────────────────────────────────────┤
│            Actix-Web HTTP Layer              │
│  Routes │ Middleware │ JWT Auth │ Sessions    │
├──────────┬──────────┬──────────┬─────────────┤
│ Resource │ App      │ Service  │ User/Wallet │
│ Provider │ Provider │ Provider │ Dashboard   │
│ Ctrl     │ Ctrl     │ Ctrl     │ Controllers │
├──────────┴──────────┴──────────┴─────────────┤
│         ServiceProvider (DI Container)        │
│    12 Trait Interfaces │ Arc<dyn Trait>       │
├──────────────┬────────────────────────────────┤
│ impl_fixtures│       impl_hero                │
│ (JSON files) │  ┌─────────┬──────────┐        │
│              │  │hero_osis│hero_ledger│        │
│              │  ├─────────┼──────────┤        │
│              │  │hero_idx │hero_embed │ (P2)  │
│              │  ├─────────┼──────────┤        │
│              │  │hero_redis│hero_coord│ (P2)  │
│              │  └─────────┴──────────┘        │
└──────────────┴────────────────────────────────┘

Deliverable

Architecture diagram (ASCII or Mermaid) committed to repo
Data flow documentation for each service trait
Hero stack integration matrix with protocols and ports
Dependency graph showing issue execution order
API surface inventory (all endpoints, which trait they use)

Acceptance Criteria

Document covers all 12 service traits and their data flows
Hero stack integration points are clearly mapped
Phase 1 and Phase 2 work items are traceable to architectural components
Document is committed to docs/architecture.md on the development branch

## Overview Create a comprehensive architecture document that maps the entire Mycelium Marketplace stack and its integration with the Hero ecosystem. This serves as the master reference for all subsequent development work. ## Current State ### Marketplace Application - **Framework**: Rust / Actix-Web 4 with Tera templates - **Frontend**: Bootstrap 5, vanilla JS, responsive (6 breakpoints) - **Database**: PostgreSQL (available but underutilized) - **Reverse Proxy**: Caddy with automatic HTTPS - **Deployment**: Docker Compose with overlay files, OpenTofu for TFGrid VMs ### Service Architecture The marketplace uses a **trait-based dependency injection** pattern with 12 service traits: | Trait | Fixture Impl | Hero Impl | Status | |-------|-------------|-----------|--------| | ProductCatalog | ✅ | ✅ | Partially wired | | UserAuth | ✅ | ✅ | Wired | | UserProfile | ✅ | ✅ | Partially wired | | OrderManager | ✅ | ✅ | Not wired in dashboard | | CartManager | ✅ | ✅ | Wired | | WalletManager | ✅ | ✅ | Not wired in dashboard | | MessagingManager | ✅ | ✅ | Partially wired | | SSHKeyManager | ✅ | ✅ | Wired | | ServiceProviderManager | ✅ | ✅ | Not wired in dashboard | | AppProviderManager | ✅ | ✅ | Partially wired | | ResourceProviderManager | ✅ | ✅ | Partially wired | | NodeRentalManager | ✅ | ✅ | Wired | ### Hero Stack Components | Component | Purpose | Integration Status | |-----------|---------|-------------------| | **hero_osis** | Schema-first data store (JSON-RPC) | ✅ Integrated via OsisClient | | **hero_ledger** | Blockchain/NEAR read-only queries | ✅ Integrated for balance queries | | **hero_index_server** | Tantivy full-text search | ❌ Not integrated | | **hero_embedder** | Vector embeddings for semantic search | ❌ Not integrated | | **hero_redis** | Session/cache persistence | ❌ Not integrated | | **hero_coordinator** | Async job orchestration | ❌ Not integrated | | hero_vault | Secret management | ❌ Not integrated | | hero_caller | External API gateway | ❌ Not integrated | | hero_certmanager | TLS certificate management | ❌ Not integrated (Caddy handles) | ### Key Problem: dashboard.rs God-Class - **7,810 lines**, 44+ handlers in a single file - **50+ direct fixture bypasses** that ignore ServiceProvider DI - Handlers create their own service instances instead of using injected `web::Data<ServiceProvider>` - This is the root cause of empty pages when running with hero_osis backend ## Target Architecture ``` ┌─────────────────────────────────────────────┐ │ Frontend (Tera + JS) │ │ Bootstrap 5 │ Responsive │ API-first ready │ ├─────────────────────────────────────────────┤ │ Actix-Web HTTP Layer │ │ Routes │ Middleware │ JWT Auth │ Sessions │ ├──────────┬──────────┬──────────┬─────────────┤ │ Resource │ App │ Service │ User/Wallet │ │ Provider │ Provider │ Provider │ Dashboard │ │ Ctrl │ Ctrl │ Ctrl │ Controllers │ ├──────────┴──────────┴──────────┴─────────────┤ │ ServiceProvider (DI Container) │ │ 12 Trait Interfaces │ Arc<dyn Trait> │ ├──────────────┬────────────────────────────────┤ │ impl_fixtures│ impl_hero │ │ (JSON files) │ ┌─────────┬──────────┐ │ │ │ │hero_osis│hero_ledger│ │ │ │ ├─────────┼──────────┤ │ │ │ │hero_idx │hero_embed │ (P2) │ │ │ ├─────────┼──────────┤ │ │ │ │hero_redis│hero_coord│ (P2) │ │ │ └─────────┴──────────┘ │ └──────────────┴────────────────────────────────┘ ``` ## Deliverable - [ ] Architecture diagram (ASCII or Mermaid) committed to repo - [ ] Data flow documentation for each service trait - [ ] Hero stack integration matrix with protocols and ports - [ ] Dependency graph showing issue execution order - [ ] API surface inventory (all endpoints, which trait they use) ## Acceptance Criteria - Document covers all 12 service traits and their data flows - Hero stack integration points are clearly mapped - Phase 1 and Phase 2 work items are traceable to architectural components - Document is committed to `docs/architecture.md` on the `development` branch