init projectmycelium
This commit is contained in:
mik-tf
269
docs/dev/design/archive/vision/parts/road-taken.md
Normal file
269
docs/dev/design/archive/vision/parts/road-taken.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user