projectmycelium/docs/dev/design/archive/vision/parts/architectural-overview.md

Project Mycelium - Architectural Overview

Single Source of Truth for AI-Assisted Development

This document serves as the comprehensive architectural reference for the Project Mycelium, designed specifically to provide AI coders and developers with a unified understanding of the system's design principles, patterns, and implementation standards.

Core Design Principles

1. Log-Free Codebase

• Policy: Zero log:: statements in main/development branches
• Rationale: Clean code, production readiness, AI-friendly development
• Implementation: 881+ log statements removed codebase-wide (2025-01-06)
• Reference: Log-Free Codebase Policy

2. Builder Pattern Architecture

• Centralized Construction: All complex objects use builder patterns
• Single Source of Truth: Eliminates duplicate initialization code
• Key Builders:
  • SessionDataBuilder (UserPersistentData)
  • ConfigurationBuilder (Environment variables)
  • ResponseBuilder (HTTP responses)
  • ServiceFactory (Service instantiation)
• Reference: Builder Pattern Architecture

3. Persistent Data Only

• No Mock Data: All MockDataService usage eliminated
• User Data Directory: Single source of truth for user data
• Persistent Storage: All data operations use user_data/ directory
• Migration Complete: 100% mock data removal achieved

4. Centralized Response Handling

• ResponseBuilder: All HTTP responses use centralized builder
• Migration Status: 78+ patterns migrated across 4 controllers
• Completed Controllers: Auth (10), Wallet (49), Product (7), Currency (12)
• Reference: ResponseBuilder Migration Guide

System Architecture

Controllers Layer

src/controllers/
├── auth.rs          ✅ ResponseBuilder migrated (10 patterns)
├── wallet.rs        ✅ ResponseBuilder migrated (49 patterns)  
├── product.rs       ✅ ResponseBuilder migrated (7 patterns)
├── currency.rs      ✅ ResponseBuilder migrated (12 patterns)
├── dashboard.rs     🔄 In progress (50+ patterns, log-free)
├── marketplace.rs   ⏳ Pending migration
├── order.rs         ⏳ Deferred (complex structure)
└── rental.rs        ⏳ Pending migration

Services Layer

src/services/
├── farmer.rs           ✅ ServiceFactory migrated
├── currency.rs         ✅ ServiceFactory migrated
├── user_persistence.rs ✅ ServiceFactory migrated
├── session_manager.rs  ✅ ServiceFactory migrated
├── node_rental.rs      ✅ ServiceFactory migrated
├── slice_rental.rs     ✅ ServiceFactory migrated
└── order.rs           ✅ ServiceFactory migrated

Utilities Layer

src/utils/
├── response_builder.rs  ✅ Centralized HTTP response handling
├── configuration.rs     ✅ ConfigurationBuilder implementation
└── data_cleanup.rs      ✅ Log-free data utilities

Models Layer

src/models/
└── builders.rs          ✅ SessionDataBuilder and other builders

Migration Progress

Completed Migrations ✅

1. ServiceFactory Migration: 100% complete

   • All service instantiations use centralized factory
   • Mock data completely eliminated
   • Persistent data access throughout

2. ConfigurationBuilder Migration: 100% complete

   • All environment variable access centralized
   • Home and Auth controllers fully migrated
   • Consistent configuration handling

3. SessionDataBuilder Migration: 100% complete

   • All UserPersistentData initialization uses builder
   • Single source of truth for user data construction
   • Consistent field handling with ..Default::default()

4. Log-Free Codebase: 100% complete

   • 881+ log statements removed codebase-wide
   • Clean compilation with zero errors
   • Production-ready code quality

5. ResponseBuilder Migration: 78 patterns complete

   • Auth Controller: 10/10 patterns ✅
   • Wallet Controller: 49/49 patterns ✅
   • Product Controller: 7/7 patterns ✅
   • Currency Controller: 12/12 patterns ✅

In Progress 🔄

1. Dashboard Controller ResponseBuilder Migration
   • 50+ HttpResponse patterns identified
   • Log cleanup completed (443 statements removed)
   • Ready for systematic migration

Pending ⏳

1. Remaining Controllers: marketplace, rental, pool, legal, docs, debug
2. Order Controller: Deferred due to structural complexity
3. Final Documentation: Consolidation and review

Development Standards

Code Quality

• Zero Compilation Errors: All migrations maintain clean builds
• Minimal Warnings: Only unused variable warnings acceptable
• Builder Pattern Usage: Mandatory for complex object construction
• Persistent Data Only: No mock data in production code

Migration Approach

• Manual Systematic Migration: Preferred over automated scripts
• Bulk All-at-Once Edits: Efficient approach for simple controllers
• Section-by-Section: For complex controllers (dashboard, order)
• Compilation Verification: cargo check after each batch

AI-Assisted Development

• Log-Free Code: Simplified analysis and pattern recognition
• Centralized Patterns: Consistent builder usage across codebase
• Single Source of Truth: This document for architectural decisions
• Clean Abstractions: Simplified code structure for AI tools

Technical Specifications

ResponseBuilder API

ResponseBuilder::ok()
    .json(data)
    .build()

ResponseBuilder::bad_request()
    .json(error_data)
    .build()

ResponseBuilder::unauthorized()
    .json(auth_error)
    .build()

ServiceFactory Usage

let service = ServiceFactory::create_farmer_service()
    .build()?;

ConfigurationBuilder Access

let config = ConfigurationBuilder::new()
    .jwt_secret()
    .gitea_client_id()
    .build();

SessionDataBuilder Pattern

let user_data = SessionDataBuilder::new_user(email);
let existing_data = SessionDataBuilder::load_or_create(email);

Performance Metrics

Before Migration

• 881+ log statements across 24 files
• Multiple mock data services
• Scattered configuration access
• Direct HttpResponse usage

After Migration

• 0 log statements (100% reduction)
• Single persistent data source
• Centralized configuration management
• Unified response handling
• Clean compilation with minimal warnings

Future Roadmap

Phase 1: Complete ResponseBuilder Migration

• Dashboard controller (in progress)
• Marketplace controller
• Rental controller
• Remaining simple controllers

Phase 2: Advanced Optimizations

• Order controller migration (complex)
• Performance optimizations
• Additional builder patterns
• Code consolidation opportunities

Phase 3: Documentation and Maintenance

• Complete architectural documentation
• Developer onboarding guides
• AI coding best practices
• Maintenance procedures

References

• Log-Free Codebase Policy
• Builder Pattern Architecture
• ResponseBuilder Migration Guide
• Migration Progress Tracker

---

Last Updated: 2025-01-06
Architecture Version: 2.0
Status: Active Development
Next Milestone: Complete Dashboard Controller Migration