projectmycelium/docs/dev/design/archive/MARKETPLACE_ARCHITECTURE.md

Project Mycelium - Grand Architecture Guide

Complete Vision & Implementation Guide for AI Coders

🎯 Project Vision

The Project Mycelium is a production-ready, fully functional e-commerce platform built in Rust that demonstrates a complete decentralized marketplace ecosystem. It's designed to be immediately testable by humans in a browser while being integration-ready for real-world deployment.

---

🏗️ Architectural Philosophy

Core Principles

1. Builder Pattern Everywhere: Every service, model, and context uses builders
2. Real Persistent Data: JSON files in ./user_data/ serve as the production database
3. Complete User Personas: Service providers, app providers, farmers, and users all fully functional
4. Integration-Ready: Designed for easy external API integration (Stripe, Grid, etc.)
5. Human-Testable: Every feature works end-to-end in the browser

Data Flow Architecture

graph TD
    A[User Action] --> B[Controller with Builder Pattern]
    B --> C[Service Layer with Business Logic]
    C --> D[JSON Database in ./user_data/]
    D --> E[Real-time UI Updates]
    E --> F[Marketplace Integration]
    F --> G[Cross-Persona Interactions]

---

📊 Data Architecture: Real Persistent Storage

JSON Database Structure

./user_data/
├── user1_at_example_com.json    # Service provider with real services
├── user2_at_example_com.json    # App provider with published apps
├── user3_at_example_com.json    # Farmer with nodes and earnings
├── user4_at_example_com.json    # Regular user with purchases
└── user5_at_example_com.json    # Mixed persona user

UserPersistentData: The Complete User Model

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UserPersistentData {
    // Core user data
    pub user_email: String,
    pub wallet_balance: Decimal,           // Real TFP balance
    pub transactions: Vec<Transaction>,    // Real transaction history
    
    // Service Provider persona
    pub services: Vec<Service>,            // Created services → marketplace
    pub service_requests: Vec<ServiceRequest>, // Client requests
    
    // App Provider persona  
    pub apps: Vec<PublishedApp>,          // Published apps → marketplace
    pub app_deployments: Vec<AppDeployment>, // Active deployments
    
    // Farmer persona
    pub nodes: Vec<FarmNode>,             // Farm nodes with real metrics
    pub farmer_earnings: Vec<EarningsRecord>, // Earnings tracking
    pub farmer_settings: Option<FarmerSettings>,
    
    // User persona
    pub user_activities: Vec<UserActivity>, // Activity tracking
    pub user_preferences: Option<UserPreferences>,
    pub usage_statistics: Option<UsageStatistics>,
    
    // Financial data
    pub pool_positions: HashMap<String, PoolPosition>, // TFP pool investments
    
    // Profile data
    pub name: Option<String>,
    pub country: Option<String>,
    pub timezone: Option<String>,
}

---

🏗️ Builder Pattern Implementation

The Builder Philosophy

Every object construction in the marketplace uses the builder pattern. This ensures:

• Consistent API: All services constructed the same way
• Validation: Required fields enforced at build time
• Extensibility: Easy to add new configuration options
• Error Handling: Proper Result types with meaningful errors

Service Builder Example

// Every service follows this pattern
let product_service = ProductService::builder()
    .currency_service(currency_service.clone())
    .cache_enabled(true)
    .default_category("compute")
    .build()?;

let farmer_service = FarmerService::builder()
    .auto_sync_enabled(true)
    .metrics_collection(true)
    .build()?;

Context Builder Pattern

// Every controller uses ContextBuilder for templates
let mut ctx = ContextBuilder::new()
    .active_page("dashboard")
    .active_section("farmer")
    .user_type("farmer")
    .build();

---

🎭 User Personas & Complete Workflows

1. Service Provider Persona ✅ COMPLETE

Workflow: Create Service → JSON Storage → Marketplace Display → Purchase by Others

// Real implementation flow
pub async fn add_service(form: ServiceForm, session: Session) -> Result<impl Responder> {
    // 1. Build service using builder pattern
    let service = Service::builder()
        .name(form.name)
        .description(form.description)
        .price(form.price)
        .build()?;
    
    // 2. Save to real JSON database
    UserPersistence::add_user_service(&user_email, service.clone())?;
    
    // 3. Register in marketplace for immediate availability
    let marketplace_product = create_marketplace_product_from_service(&service);
    MockDataService::instance().lock().unwrap().add_product(marketplace_product);
    
    // Service now appears in /marketplace/services immediately
}

2. App Provider Persona ✅ COMPLETE

Workflow: Publish App → JSON Storage → Marketplace Display → Deployment Tracking

pub async fn publish_app(form: AppForm, session: Session) -> Result<impl Responder> {
    let app = PublishedApp::builder()
        .name(form.name)
        .category(form.category)
        .version("1.0.0")
        .build()?;
    
    UserPersistence::add_user_app(&user_email, app.clone())?;
    
    // Auto-register in marketplace
    let marketplace_product = create_marketplace_product_from_app(&app);
    MockDataService::instance().lock().unwrap().add_product(marketplace_product);
}

3. Farmer Persona 🔄 TO COMPLETE

Workflow: Manage Nodes → Track Earnings → Monitor Performance → Marketplace Integration

Required Implementation:

// src/controllers/dashboard.rs
pub async fn farmer_dashboard(tmpl: web::Data<Tera>, session: Session) -> Result<impl Responder> {
    let farmer_service = FarmerService::builder().build()?;
    let user_email = session.get::<String>("user_email")?.unwrap();
    
    // Load real farmer data from JSON
    let nodes = farmer_service.get_farmer_nodes(&user_email);
    let earnings = farmer_service.get_farmer_earnings(&user_email);
    let stats = farmer_service.get_farmer_statistics(&user_email);
    
    let mut ctx = ContextBuilder::new()
        .active_page("dashboard")
        .active_section("farmer")
        .build();
    
    ctx.insert("nodes", &nodes);
    ctx.insert("earnings", &earnings);
    ctx.insert("stats", &stats);
    
    render_template(&tmpl, "dashboard/farmer.html", &ctx)
}

4. User Persona 🔄 TO COMPLETE

Workflow: Browse Marketplace → Purchase → Track Orders → Manage Profile

Required Implementation:

pub async fn user_dashboard(tmpl: web::Data<Tera>, session: Session) -> Result<impl Responder> {
    let user_service = UserService::builder().build()?;
    let user_email = session.get::<String>("user_email")?.unwrap();
    
    // Load real user data from JSON
    let activities = user_service.get_user_activities(&user_email, Some(10));
    let purchases = user_service.get_purchase_history(&user_email);
    let wallet_data = UserPersistence::load_user_data(&user_email);
    
    let mut ctx = ContextBuilder::new()
        .active_page("dashboard")
        .active_section("user")
        .build();
    
    ctx.insert("activities", &activities);
    ctx.insert("purchases", &purchases);
    ctx.insert("wallet_balance", &wallet_data.wallet_balance);
    
    render_template(&tmpl, "dashboard/user.html", &ctx)
}

---

🔄 Complete Data Flow: Creation to Purchase

Service Creation → Marketplace → Purchase Flow

sequenceDiagram
    participant SP as Service Provider
    participant JSON as JSON Database
    participant MP as Marketplace
    participant U as User/Buyer
    
    SP->>JSON: Create service (real data)
    JSON->>MP: Auto-register in marketplace
    MP->>U: Service visible in /marketplace/services
    U->>MP: Add to cart
    MP->>JSON: Create order (real transaction)
    JSON->>SP: Update earnings (real money)

Real Data Examples

// user_data/service_provider_at_example_com.json
{
  "user_email": "provider@example.com",
  "wallet_balance": 2450.75,
  "services": [
    {
      "id": "svc_001",
      "name": "WordPress Development",
      "description": "Custom WordPress solutions",
      "price_per_hour": 75,
      "status": "Active",
      "clients": 12,
      "total_hours": 240,
      "rating": 4.8
    }
  ],
  "transactions": [
    {
      "id": "txn_001",
      "amount": 375.00,
      "transaction_type": "ServicePayment",
      "timestamp": "2025-06-19T10:30:00Z",
      "status": "Completed"
    }
  ]
}

---

🎨 Frontend Architecture: Complete UX

Dashboard Navigation Structure

/dashboard/
├── service-provider/     ✅ Complete
│   ├── overview         # Service stats, revenue
│   ├── services         # Manage services
│   └── requests         # Client requests
├── app-provider/        ✅ Complete  
│   ├── overview         # App stats, deployments
│   ├── apps             # Manage apps
│   └── deployments      # Active deployments
├── farmer/              🔄 To Complete
│   ├── overview         # Node stats, earnings
│   ├── nodes            # Node management
│   └── earnings         # Earnings tracking
└── user/                🔄 To Complete
    ├── overview         # Activity, purchases
    ├── purchases        # Purchase history
    └── profile          # Profile management

Marketplace Structure

/marketplace/            ✅ Complete
├── dashboard           # Overview with featured items
├── compute             # Compute resources
├── 3nodes             # Physical hardware
├── gateways            # Network gateways
├── applications        # Published apps
└── services            # Human services

---

🔧 Implementation Patterns for AI Coders

1. Controller Pattern

// ALWAYS follow this pattern for new controllers
impl SomeController {
    pub async fn some_action(tmpl: web::Data<Tera>, session: Session) -> Result<impl Responder> {
        // 1. Initialize services with builders
        let service = SomeService::builder()
            .config_option(value)
            .build()?;
        
        // 2. Get user from session
        let user_email = session.get::<String>("user_email")?.unwrap();
        
        // 3. Load real data from JSON persistence
        let data = service.get_user_data(&user_email);
        
        // 4. Build context
        let mut ctx = ContextBuilder::new()
            .active_page("dashboard")
            .active_section("section_name")
            .build();
        
        // 5. Add data to context
        ctx.insert("data", &data);
        
        // 6. Render template
        render_template(&tmpl, "template_path.html", &ctx)
    }
}

2. Service Pattern

// ALWAYS implement services with builders
#[derive(Clone)]
pub struct SomeService {
    config: ServiceConfig,
}

impl SomeService {
    pub fn builder() -> SomeServiceBuilder {
        SomeServiceBuilder::new()
    }
    
    pub fn get_user_data(&self, user_email: &str) -> Vec<SomeData> {
        // Load from JSON persistence
        if let Some(persistent_data) = UserPersistence::load_user_data(user_email) {
            persistent_data.some_field
        } else {
            Vec::new()
        }
    }
    
    pub fn save_user_data(&self, user_email: &str, data: SomeData) -> Result<(), String> {
        // Save to JSON persistence
        let mut persistent_data = UserPersistence::load_user_data(user_email)
            .unwrap_or_else(|| UserPersistence::create_default_user_data(user_email));
        
        persistent_data.some_field.push(data);
        UserPersistence::save_user_data(user_email, &persistent_data)
    }
}

3. Model Pattern

// ALWAYS create builders for complex models
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SomeModel {
    pub id: String,
    pub name: String,
    pub status: String,
    // ... other fields
}

#[derive(Default)]
pub struct SomeModelBuilder {
    id: Option<String>,
    name: Option<String>,
    status: Option<String>,
}

impl SomeModelBuilder {
    pub fn new() -> Self {
        Self::default()
    }
    
    pub fn id(mut self, id: impl Into<String>) -> Self {
        self.id = Some(id.into());
        self
    }
    
    pub fn name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }
    
    pub fn build(self) -> Result<SomeModel, String> {
        Ok(SomeModel {
            id: self.id.ok_or("id is required")?,
            name: self.name.ok_or("name is required")?,
            status: self.status.unwrap_or_else(|| "Active".to_string()),
        })
    }
}

---

🚀 Integration Readiness

Current State: Production-Ready Marketplace

The marketplace is fully functional with real persistent data. What makes it "integration-ready":

1. Payment Integration: Replace JSON transaction creation with Stripe API calls
2. Grid Integration: Connect farmer nodes to real ThreeFold Grid API
3. Container Deployment: Connect app publishing to real container orchestration
4. Real-time Monitoring: Connect node metrics to actual hardware

Integration Points

// Example: Easy Stripe integration
pub async fn process_payment(order: &Order) -> Result<PaymentResult, String> {
    // Current: Save to JSON
    // Future: Call Stripe API
    stripe::charge_customer(&order.payment_details, order.total_amount)
}

// Example: Easy Grid integration  
pub async fn deploy_node(node: &FarmNode) -> Result<NodeStatus, String> {
    // Current: Update JSON status
    // Future: Call Grid API
    grid_api::register_node(&node.specs, &node.location)
}

---

📋 Implementation Checklist for AI Coders

To Complete Farmer Dashboard

• Create src/services/farmer.rs with FarmerService and builder
• Add farmer methods to src/controllers/dashboard.rs
• Create src/views/dashboard/farmer.html template
• Add farmer routes to src/routes/mod.rs
• Enhance FarmNode model with builder pattern

To Complete User Dashboard

• Create src/services/user_service.rs with UserService and builder
• Add user methods to src/controllers/dashboard.rs
• Create src/views/dashboard/user.html template
• Add user routes to src/routes/mod.rs
• Enhance user activity models with builders

Key Implementation Rules

1. Always use builders for service and model construction
2. Always load real data from UserPersistence::load_user_data()
3. Always use ContextBuilder for template contexts
4. Always follow the Controller → Service → Persistence pattern
5. Always make data immediately visible in marketplace after creation

---

🎯 Success Criteria

Human Testing Scenarios

A human tester should be able to:

1. Login as farmer → See nodes dashboard → View earnings → Manage nodes
2. Login as user → See purchase history → View wallet → Browse marketplace
3. Switch personas → See completely different, relevant dashboards
4. Create content → See it immediately in marketplace → Purchase as different user
5. Complete workflows → Service creation → Marketplace → Purchase → Revenue tracking

Technical Success

• All personas have complete dashboard functionality
• All data persists in JSON database
• All interactions work end-to-end in browser
• All code follows established builder patterns
• All templates use consistent styling and navigation

---

🏆 The Grand Vision

The Project Mycelium represents a complete, production-ready e-commerce ecosystem that demonstrates:

• Modern Rust Architecture: Builder patterns, proper error handling, clean separation of concerns
• Real Data Persistence: JSON database with complete user lifecycle management
• Multi-Persona Platform: Service providers, app providers, farmers, and users all fully functional
• Complete UX: Every feature testable by humans in browser
• Integration Readiness: Easy to connect to external APIs and services

This is not a prototype or demo - it's a fully functional marketplace ready for real-world deployment with minimal integration work.

---

📚 File Structure Reference

projectmycelium/
├── src/
│   ├── controllers/
│   │   ├── dashboard.rs      # All dashboard functionality
│   │   ├── marketplace.rs    # Marketplace browsing
│   │   └── order.rs         # Cart and checkout
│   ├── services/
│   │   ├── product.rs       # Product management
│   │   ├── currency.rs      # Multi-currency support
│   │   ├── user_persistence.rs # JSON database operations
│   │   ├── farmer.rs        # 🔄 TO CREATE
│   │   └── user_service.rs  # 🔄 TO CREATE
│   ├── models/
│   │   ├── builders.rs      # All builder patterns
│   │   ├── user.rs         # User data structures
│   │   └── product.rs      # Product data structures
│   └── views/
│       ├── marketplace/     # Marketplace templates
│       └── dashboard/       # Dashboard templates
├── user_data/              # JSON database
└── docs/
    ├── MARKETPLACE_ARCHITECTURE.md  # Existing architecture doc
    └── AI_IMPLEMENTATION_GUIDE.md   # Step-by-step implementation

This architecture ensures that any AI coder can understand the complete system and implement the remaining functionality following established patterns.