# 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](./log-free-codebase-policy.md)

### 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](./builder-pattern-architecture.md)

### 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](./response-builder-migration.md)

## 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
```rust
ResponseBuilder::ok()
    .json(data)
    .build()

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

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

### ServiceFactory Usage
```rust
let service = ServiceFactory::create_farmer_service()
    .build()?;
```

### ConfigurationBuilder Access
```rust
let config = ConfigurationBuilder::new()
    .jwt_secret()
    .gitea_client_id()
    .build();
```

### SessionDataBuilder Pattern
```rust
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](./log-free-codebase-policy.md)
- [Builder Pattern Architecture](./builder-pattern-architecture.md)
- [ResponseBuilder Migration Guide](./response-builder-migration.md)
- [Migration Progress Tracker](./builder-pattern-progress-tracker.md)

---

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