# Project Mycelium: Road Taken - Decision Trail

**Document Purpose**: Track architectural decisions, refactoring choices, and evolution path for future DevOps teams and maintainers.

**Last Updated**: 2025-08-04  
**Status**: Active Development

---

## Table of Contents
1. [Decision Log](#decision-log)
2. [Architecture Evolution](#architecture-evolution)
3. [Refactoring Decisions](#refactoring-decisions)
4. [Technical Debt Resolution](#technical-debt-resolution)
5. [Future Considerations](#future-considerations)

---

## Decision Log

### Decision #001: TFP → TFC Credits System Refactor
**Date**: 2025-08-04  
**Status**: ✅ **APPROVED** - Implementation in Progress  
**Decision Makers**: Development Team  

#### **Problem Statement**
The marketplace used a hybrid TFP (ThreeFold Points) to USD conversion system that created:
- Complex conversion logic throughout the codebase
- Confusing user experience with dual currency displays
- Maintenance overhead with exchange rate calculations
- Difficulty in adjusting credit values without code changes

#### **Options Considered**

| Option | Description | Pros | Cons | Decision |
|--------|-------------|------|------|----------|
| **A. Keep Hybrid TFP/USD** | Maintain current dual system | No breaking changes | Complex, confusing, hard to maintain | ❌ Rejected |
| **B. Pure USD Only** | Remove TFP entirely, use USD | Simple, familiar | Loses ThreeFold branding | ❌ Rejected |
| **C. TFP → TFC (Configurable)** | Rename to ThreeFold Credits, 1 TFC = 1 USD (configurable) | Clean, brandable, flexible, industry standard | Requires refactor | ✅ **SELECTED** |

#### **Decision Rationale**
- **Industry Standard**: Follows AWS Credits, Google Cloud Credits, Azure Credits model
- **User Experience**: Simple mental model (1 credit = 1 dollar)
- **Developer Experience**: Clean codebase, no conversion logic
- **Business Flexibility**: Credit value adjustable via configuration
- **Maintainability**: Single currency system, easier to debug and extend

#### **Implementation Strategy**
1. **Phase 1**: Global rename TFP → TFC throughout codebase
2. **Phase 2**: Remove all conversion logic and exchange rate calculations
3. **Phase 3**: Implement configurable credit value system
4. **Phase 4**: Update UI/UX to reflect simplified credit system

#### **Success Criteria**
- [ ] Zero TFP references remain in codebase
- [ ] All calculations use TFC directly (no conversions)
- [ ] Credit value configurable via admin panel/config file
- [ ] User interface shows clear TFC branding
- [ ] All tests pass with new credit system

#### **Impact Assessment**
- **Breaking Changes**: Yes - API responses change from TFP to TFC
- **Database Migration**: Required - update all currency fields
- **User Impact**: Positive - simpler, clearer credit system
- **DevOps Impact**: Simplified deployment, fewer config parameters

---

### Decision #002: Database Migration to Supabase
**Date**: 2025-08-04  
**Status**: ✅ **APPROVED** - Architecture Documented  
**Decision Makers**: Development Team  

#### **Problem Statement**
Current JSON file-based storage with git versioning is not scalable for production use.

#### **Solution Selected**
Supabase self-hosted (PostgreSQL + PostgREST + Auth + Realtime) for:
- Scalable database backend
- REST API auto-generation
- Built-in authentication
- Real-time subscriptions
- Full open-source stack

#### **Deployment Strategy**
- **Phase 1**: Local development with Docker Compose
- **Phase 2**: Production single-node on ThreeFold Grid
- **Phase 3**: High Availability k3s cluster deployment

---

### Decision #003: High Availability Architecture
**Date**: 2025-08-04  
**Status**: ✅ **APPROVED** - Phase 3 Implementation  
**Decision Makers**: Development Team  

#### **Problem Statement**
Need enterprise-grade high availability with no single point of failure.

#### **Solution Selected**
k3s clusters with embedded etcd for true multi-master HA:
- **ThreeFold Grid**: Use `tfgrid-k3s` automation (Terraform + Ansible + WireGuard)
- **Multi-Cloud**: Use `k3scluster` automation (Tailscale networking)
- **Configuration**: 3-5 master nodes + multiple workers

#### **Benefits**
- Zero downtime deployments
- Automatic failover
- Horizontal scaling
- Industry-standard tooling

---

## Architecture Evolution

### Phase 1: Legacy Architecture (Pre-2025)
```
[Frontend] → [Rust Backend] → [JSON Files + Git]
              ↓
         [TFP ↔ USD Conversion Logic]
```

**Problems**:
- Non-scalable file-based storage
- Complex dual currency system
- Manual git-based versioning

### Phase 2: Current Transition (2025)
```
[Frontend] → [Rust Backend] → [Supabase PostgreSQL]
              ↓                    ↓
         [TFC Credits Only]    [PostgREST API]
                                   ↓
                              [Auth + Realtime]
```

**Improvements**:
- Scalable PostgreSQL database
- Simplified single currency (TFC)
- Auto-generated REST API
- Built-in authentication

### Phase 3: Target HA Architecture (Future)
```
[Load Balancer] → [k3s Cluster]
                      ↓
    [Multiple Rust Backend Pods] → [HA PostgreSQL Cluster]
                      ↓                    ↓
              [TFC Credits System]    [Supabase Stack]
```

**Benefits**:
- No single point of failure
- Horizontal scaling
- Enterprise-grade reliability

---

## Refactoring Decisions

### TFP → TFC Refactor Details

#### **Naming Conventions**
- **Old**: TFP, ThreeFold Points, tfp_amount, buyTFP()
- **New**: TFC, ThreeFold Credits, tfc_amount, buyCredits()

#### **Code Changes Required**

| Component | Changes | Files Affected |
|-----------|---------|----------------|
| **Rust Backend** | Remove conversion logic, update structs | `models/`, `controllers/`, `services/` |
| **Frontend HTML** | Update all UI text and form labels | `views/dashboard/` |
| **JavaScript** | Rename functions and variables | `*.html` inline JS |
| **Database Schema** | Migrate currency fields | Migration scripts |
| **API Endpoints** | Update request/response formats | `routes/mod.rs` |

#### **Configuration System**
```rust
// New configurable credit system
pub struct MarketplaceConfig {
    pub tfc_to_usd_rate: Decimal,     // Default: 1.0
    pub credit_currency_code: String, // "TFC"
    pub credit_display_name: String,  // "ThreeFold Credits"
    pub credit_symbol: String,        // "TFC"
}
```

---

## Technical Debt Resolution

### Resolved Issues
1. **Hybrid Currency Complexity** → Single TFC system
2. **File-based Storage** → PostgreSQL database
3. **Manual Scaling** → Container orchestration ready

### Remaining Technical Debt
- [ ] Legacy API endpoints (maintain backward compatibility)
- [ ] Old configuration format migration
- [ ] Performance optimization for high-traffic scenarios

---

## Future Considerations

### Potential Enhancements
1. **Multi-Currency Support**: If needed, add other currencies while keeping TFC as base
2. **Credit Packages**: Bulk credit purchase discounts
3. **Credit Expiration**: Optional expiry dates for credits
4. **Credit Transfers**: Peer-to-peer credit transfers
5. **Credit Analytics**: Usage tracking and reporting

### Scalability Roadmap
1. **Phase 1**: Single-node production (current)
2. **Phase 2**: Multi-node k3s cluster
3. **Phase 3**: Multi-region deployment
4. **Phase 4**: Global CDN and edge computing

### Monitoring & Observability
- Application metrics via Prometheus
- Log aggregation via Loki
- Distributed tracing via Jaeger
- Health checks and alerting

---

## DevOps Guidelines

### For Future Maintainers

#### **Understanding the Credit System**
- **TFC = ThreeFold Credits**: The single currency used throughout
- **1 TFC = 1 USD by default**: Configurable via `marketplace.config`
- **No Conversions**: All calculations use TFC directly

#### **Configuration Management**
```bash
# Adjust credit value
export TFC_USD_RATE=1.0  # 1 TFC = 1 USD

# Update via config file
echo "tfc_to_usd_rate = 1.0" >> marketplace.config
```

#### **Database Schema**
- All currency fields store TFC amounts
- No exchange rate tables needed
- Simple decimal precision for credits

#### **Deployment Notes**
- Use provided Docker Compose for development
- Follow k3s automation for production HA
- Monitor credit balance calculations in logs

---

## Conclusion

The TFP → TFC refactor represents a strategic shift toward:
- **Simplicity**: Single currency system
- **Flexibility**: Configurable credit values
- **Maintainability**: Clean, documented codebase
- **Scalability**: Modern database and orchestration

This decision trail ensures future teams understand the rationale and can continue evolving the marketplace architecture effectively.

---

**Next Steps**: Execute TFP → TFC refactor implementation as documented in the architecture plan.