# 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**
```mermaid
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**
```rust
#[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**
```rust
// 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**
```rust
// 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
```rust
// 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
```rust
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**:
```rust
// 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**:
```rust
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**
```mermaid
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**
```json
// 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**
```rust
// 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**
```rust
// 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**
```rust
// 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**
```rust
// 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.