init projectmycelium

2025-09-01 21:37:01 -04:00
commit b41efb0e99
319 changed files with 128160 additions and 0 deletions
--- a/docs/dev/design/archive/MARKETPLACE_ARCHITECTURE.md
+++ b/docs/dev/design/archive/MARKETPLACE_ARCHITECTURE.md
@@ -0,0 +1,531 @@
+# 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.