init projectmycelium

2025-09-01 21:37:01 -04:00
commit b41efb0e99
319 changed files with 128160 additions and 0 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,111 @@
+# Project Mycelium Documentation
+
+## Quick Links
+
+### 🚨 Emergency Troubleshooting
+- **[JSON Parsing Errors](./dev/guides/troubleshooting-json-errors.md)** - Quick fixes for common data issues
+
+### 📚 Development Guides
+- **[Data Validation Guide](./dev/guides/data-validation-guide.md)** - Comprehensive validation tools and processes
+
+### 🏗️ Design Documentation
+- **[User Dashboard](./dev/design/USER_DASHBOARD.md)** - User dashboard architecture and design
+- **[Farmer Dashboard](./dev/design/FARMER_DASHBOARD.md)** - Farmer dashboard specifications
+- **[Marketplace Architecture](./dev/design/MARKETPLACE_ARCHITECTURE.md)** - Overall system architecture
+
+### 🚀 Operations
+- **[Deployment Guide](./ops/deployment.md)** - Production deployment procedures
+
+## Common Tasks
+
+### Fix JSON Parsing Errors
+```bash
+cd projectmycelium
+python3 scripts/fix_user_data.py
+cargo run
+```
+
+### Validate User Data
+```bash
+# Quick validation and fixes with Python
+python3 scripts/fix_user_data.py
+
+# Manual validation using Rust tools
+# (See data validation guide for detailed usage)
+```
+
+### Schema Updates
+1. Update Rust structs in `src/models/user.rs`
+2. Update validation tools if needed
+3. Run `python3 scripts/fix_user_data.py` to migrate existing data
+4. Test with `cargo run`
+
+## Tools Overview
+
+| Tool | Location | Purpose | When to Use |
+|------|----------|---------|-------------|
+| `fix_user_data.py` | `scripts/` | Quick automated fixes | JSON parsing errors, routine maintenance |
+| `data_validator.rs` | `src/utils/` | Detailed validation | Development, complex schema analysis |
+| Troubleshooting guide | `dev/guides/` | Emergency reference | When application won't start |
+| Data validation guide | `dev/guides/` | Comprehensive reference | Understanding validation process |
+
+## Documentation Structure
+
+```
+projectmycelium/docs/
+├── README.md                                    # This file - main documentation index
+├── dev/                                         # Development documentation
+│   ├── guides/                                  # How-to guides and procedures
+│   │   ├── data-validation-guide.md             # Data validation tools and processes
+│   │   └── troubleshooting-json-errors.md       # Quick JSON error fixes
+│   └── design/                                  # Architecture and design docs
+│       ├── USER_DASHBOARD.md                    # User dashboard design
+│       ├── FARMER_DASHBOARD.md                  # Farmer dashboard design
+│       └── MARKETPLACE_ARCHITECTURE.md          # System architecture
+└── ops/                                         # Operations documentation
+    └── deployment.md                            # Deployment procedures
+```
+
+## Related Files
+
+```
+projectmycelium/
+├── docs/                                        # This documentation
+├── scripts/
+│   └── fix_user_data.py                        # Python validation script
+├── src/utils/
+│   ├── data_validator.rs                       # Rust validation utility
+│   └── mod.rs                                   # Utils module integration
+├── user_data/                                   # User JSON files
+└── src/models/user.rs                          # Schema definitions
+```
+
+## Getting Started
+
+### For Immediate Issues
+1. **JSON parsing errors:** Start with [troubleshooting-json-errors.md](./dev/guides/troubleshooting-json-errors.md)
+2. **Run the fix script:** `python3 scripts/fix_user_data.py`
+
+### For Development
+1. **Understanding data validation:** Read [data-validation-guide.md](./dev/guides/data-validation-guide.md)
+2. **Dashboard development:** Check design docs in `dev/design/`
+3. **System architecture:** See [MARKETPLACE_ARCHITECTURE.md](./dev/design/MARKETPLACE_ARCHITECTURE.md)
+
+### For Operations
+1. **Deployment:** Follow [deployment.md](./ops/deployment.md)
+2. **Maintenance:** Use validation tools regularly
+
+## Contributing
+
+When adding new features that change data schemas:
+1. Update the relevant structs in `src/models/`
+2. Update validation tools in `src/utils/` and `scripts/`
+3. Test with existing user data using `python3 scripts/fix_user_data.py`
+4. Document changes in the appropriate guide
+5. Update this README if new documentation is added
+
+## Recent Updates
+
+- **Data Validation System:** Added comprehensive validation tools to handle JSON schema mismatches
+- **Emergency Troubleshooting:** Created quick-reference guide for common JSON parsing errors
+- **Validation Scripts:** Python script in `scripts/` directory for automated data fixes