270 lines
8.7 KiB
Markdown
270 lines
8.7 KiB
Markdown
# 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.
|