projectmycelium/docs/dev/design/archive/vision/parts/road-taken.md

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
2. Architecture Evolution
3. Refactoring Decisions
4. Technical Debt Resolution
5. 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

// 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

# 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.