Hyperloop-UPV · msanlli · Jun 5, 2025 · Jun 5, 2025 · Jun 5, 2025 · Jun 5, 2025
diff --git a/DOCUMENTATION_REORGANIZATION.md b/DOCUMENTATION_REORGANIZATION.md
@@ -0,0 +1,124 @@
+# Documentation Reorganization Summary
+
+This document outlines the reorganization of project documentation from scattered files to a centralized `docs/` folder structure.
+
+## 📁 New Documentation Structure
+
+```
+docs/
+├── README.md                    # Main documentation index
+├── architecture/
+│   └── README.md               # System architecture overview
+├── development/
+│   ├── DEVELOPMENT.md          # Development setup guide
+│   ├── CROSS_PLATFORM_DEV_SUMMARY.md  # Cross-platform scripts documentation
+│   └── scripts.md              # Scripts reference guide
+├── guides/
+│   └── getting-started.md      # New user getting started guide
+└── troubleshooting/
+    └── BLCU_FIX_SUMMARY.md     # BLCU repair documentation
+```
+
+## 📋 File Migrations
+
+### Moved Files
+| Original Location | New Location | Status |
+|-------------------|--------------|--------|
+| `DEVELOPMENT.md` | `docs/development/DEVELOPMENT.md` | ✅ Moved |
+| `CROSS_PLATFORM_DEV_SUMMARY.md` | `docs/development/CROSS_PLATFORM_DEV_SUMMARY.md` | ✅ Moved |
+| `scripts/README.md` | `docs/development/scripts.md` | ✅ Moved |
+| `backend/BLCU_FIX_SUMMARY.md` | `docs/troubleshooting/BLCU_FIX_SUMMARY.md` | ✅ Moved |
+
+### New Files Created
+| File | Purpose |
+|------|---------|
+| `docs/README.md` | Main documentation index with navigation |
+| `docs/architecture/README.md` | System architecture overview |
+| `docs/guides/getting-started.md` | Comprehensive new user guide |
+| `scripts/README.md` | Quick reference pointing to full docs |
+
+### Updated Files
+| File | Changes |
+|------|---------|
+| `README.md` | Added documentation section with quick links |
+| `docs/development/scripts.md` | Updated paths for new location |
+
+## 🎯 Benefits of New Structure
+
+### 1. **Improved Organization**
+- Clear categorization by purpose (development, architecture, guides, troubleshooting)
+- Logical hierarchy that scales as documentation grows
+- Centralized location for all project documentation
+
+### 2. **Better Discoverability**
+- Single entry point through `docs/README.md`
+- Clear navigation between related documents
+- Quick links in main README for common tasks
+
+### 3. **Enhanced User Experience**
+- Dedicated getting started guide for new users
+- Platform-specific guidance clearly organized
+- Troubleshooting docs easily accessible
+
+### 4. **Maintainability**
+- Related documentation grouped together
+- Easier to update and maintain consistency
+- Clear ownership and responsibility areas
+
+## 🚀 How to Use the New Structure
+
+### For New Users
+1. Start with [`docs/guides/getting-started.md`](docs/guides/getting-started.md)
+2. Follow platform-specific setup in [`docs/development/DEVELOPMENT.md`](docs/development/DEVELOPMENT.md)
+3. Refer to troubleshooting docs if needed
+
+### For Developers
+1. Check [`docs/development/`](docs/development/) for all development-related docs
+2. Use [`docs/architecture/`](docs/architecture/) to understand system design
+3. Reference [`docs/development/scripts.md`](docs/development/scripts.md) for tooling
+
+### For Contributors
+1. Review existing documentation structure before adding new docs
+2. Place new documentation in appropriate category folders
+3. Update main index (`docs/README.md`) when adding major new sections
+
+## 📝 Documentation Guidelines
+
+### Placement Rules
+- **Development docs** → `docs/development/`
+- **Architecture docs** → `docs/architecture/`  
+- **User guides** → `docs/guides/`
+- **Troubleshooting** → `docs/troubleshooting/`
+- **Component-specific** → Keep in respective component directories
+
+### Linking Guidelines
+- Use relative paths for internal documentation links
+- Update `docs/README.md` index when adding major new documents
+- Cross-reference related documentation where helpful
+
+### File Naming
+- Use lowercase with hyphens: `getting-started.md`
+- Use descriptive names that indicate content purpose
+- Keep README.md files for directory overviews
+
+## 🔗 Key Entry Points
+
+### Primary Documentation
+- **[docs/README.md](docs/README.md)** - Main documentation hub
+- **[README.md](README.md)** - Project overview with quick start
+
+### Quick Access
+- **New Users**: [Getting Started Guide](docs/guides/getting-started.md)
+- **Developers**: [Development Setup](docs/development/DEVELOPMENT.md)
+- **Troubleshooting**: [Common Issues](docs/troubleshooting/BLCU_FIX_SUMMARY.md)
+
+## 🎉 Migration Complete
+
+The documentation reorganization provides:
+- ✅ Better organization and navigation
+- ✅ Improved new user experience  
+- ✅ Clearer separation of concerns
+- ✅ Scalable structure for future growth
+- ✅ Maintained backward compatibility through redirect notes
+
+All existing functionality remains accessible while providing a much better documentation experience for users, developers, and contributors.
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ Download the latest release, unzip it and run the executable compatible with you
 
 ### For Developers
 
-See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed setup instructions. Quick start:
+See our comprehensive [Documentation](./docs/README.md) or jump to [Getting Started](./docs/guides/getting-started.md). Quick start:
 
 ```bash
 # Clone and setup
@@ -34,7 +34,17 @@ When using the Control Station make sure that you have configured your IP as the
 
 To change the ADJ branch from `main`, change the option `adj/branch` at the end of the `config.toml` with the name of the branch you want to use or leave it blank if you'll be making use of a custom ADJ.
 
-### Contributing
+## Documentation
+
+📚 **[Complete Documentation](./docs/README.md)** - All guides and references
+
+### Quick Links
+- 🚀 **[Getting Started](./docs/guides/getting-started.md)** - New user guide
+- 🛠️ **[Development Setup](./docs/development/DEVELOPMENT.md)** - Developer environment setup  
+- 🏗️ **[Architecture](./docs/architecture/README.md)** - System design overview
+- 🔧 **[Troubleshooting](./docs/troubleshooting/BLCU_FIX_SUMMARY.md)** - Common issues and fixes
+
+## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for ways to contribute to the Control Station.
 

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,79 @@
+# Hyperloop H10 Documentation
+
+Welcome to the Hyperloop UPV H10 Control Station documentation. This directory contains comprehensive guides for developers, operators, and contributors.
+
+## 📚 Documentation Structure
+
+### 🛠️ Development
+- **[Development Setup](development/DEVELOPMENT.md)** - Complete guide to setting up your development environment
+- **[Cross-Platform Scripts](development/CROSS_PLATFORM_DEV_SUMMARY.md)** - Cross-platform development script documentation
+- **[Scripts Reference](development/scripts.md)** - Detailed reference for all development scripts
+
+### 🏗️ Architecture
+- **[System Overview](architecture/README.md)** - High-level system architecture
+- **[Backend Architecture](architecture/backend.md)** - Go backend design and components
+- **[Frontend Architecture](architecture/frontend.md)** - React frontend applications structure
+- **[Communication Protocols](architecture/protocols.md)** - WebSocket and network communication
+
+### 📖 Guides
+- **[Getting Started](guides/getting-started.md)** - Quick start guide for new users
+- **[Configuration](guides/configuration.md)** - System configuration and ADJ specifications
+- **[Deployment](guides/deployment.md)** - Production deployment instructions
+- **[Testing](guides/testing.md)** - Testing strategies and tools
+
+### 🔧 Troubleshooting
+- **[BLCU Fix Summary](troubleshooting/BLCU_FIX_SUMMARY.md)** - Boot Loader Control Unit repair documentation
+- **[Common Issues](troubleshooting/common-issues.md)** - Frequently encountered problems and solutions
+- **[Platform-Specific Issues](troubleshooting/platform-issues.md)** - OS-specific troubleshooting
+
+## 🚀 Quick Start
+
+New to the project? Start here:
+
+1. **[Getting Started Guide](guides/getting-started.md)** - Overview and first steps
+2. **[Development Setup](development/DEVELOPMENT.md)** - Set up your development environment
+3. **[Architecture Overview](architecture/README.md)** - Understand the system design
+
+## 📋 Additional Resources
+
+### Root Level Documentation
+- **[README.md](../README.md)** - Project overview and quick setup
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - How to contribute to the project
+- **[CLAUDE.md](../CLAUDE.md)** - AI assistant instructions for code development
+
+### Component-Specific Documentation
+- **[Common Frontend](../common-front/README.md)** - Shared React component library
+- **[Backend Captures](../backend/captures/README.md)** - Network packet capture samples
+
+### GitHub Templates
+- **[Bug Reports](../.github/ISSUE_TEMPLATE/bug.md)** - Bug report template
+- **[Feature Requests](../.github/ISSUE_TEMPLATE/feature.md)** - Feature request template
+- **[Task Templates](../.github/ISSUE_TEMPLATE/task.md)** - Task template
+
+## 🔄 Documentation Updates
+
+This documentation is actively maintained. If you find errors or have suggestions:
+
+1. Check existing [issues](https://github.com/HyperloopUPV-H8/h9-backend/issues)
+2. Create a new issue using the appropriate template
+3. Submit a pull request with improvements
+
+## 📝 Contributing to Documentation
+
+When adding new documentation:
+
+1. **Development docs** → `docs/development/`
+2. **Architecture docs** → `docs/architecture/`
+3. **User guides** → `docs/guides/`
+4. **Troubleshooting** → `docs/troubleshooting/`
+5. **Component-specific** → Keep in respective component directories
+
+Follow the existing markdown style and include:
+- Clear headings and structure
+- Code examples where applicable
+- Cross-references to related documentation
+- Platform-specific notes when relevant
+
+---
+
+*Last updated: $(date '2025-06-03')*
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
@@ -0,0 +1,107 @@
+# System Architecture Overview
+
+The Hyperloop H10 Control Station is a real-time monitoring and control system designed for managing pod operations during testing and competition runs.
+
+## High-Level Architecture
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│                 │    │                 │    │                 │
+│   Pod Sensors   │◄──►│   Backend       │◄──►│   Frontend      │
+│   & Boards      │    │   (Go Server)   │    │   (React Apps)  │
+│                 │    │                 │    │                 │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │                 │
+                    │   Data Logger   │
+                    │   & Storage     │
+                    │                 │
+                    └─────────────────┘
+```
+
+## Core Components
+
+### 1. Backend (Go)
+- **Location**: `backend/`
+- **Purpose**: Real-time data processing and communication hub
+- **Key Features**:
+  - TCP/UDP packet processing
+  - WebSocket server for frontend communication
+  - TFTP server for firmware updates
+  - Data logging and storage
+  - Board abstraction and management
+
+### 2. Frontend Applications (React/TypeScript)
+- **Common Frontend**: `common-front/` - Shared component library
+- **Control Station**: `control-station/` - Main operational interface
+- **Ethernet View**: `ethernet-view/` - Network debugging and monitoring
+
+### 3. Supporting Tools
+- **Packet Sender**: `packet-sender/` - Testing and simulation tool
+- **Updater**: `updater/` - System update management
+- **Scripts**: `scripts/` - Development and deployment automation
+
+## Data Flow
+
+1. **Sensor Data Collection**
+   - Pod sensors send data via Ethernet/TCP
+   - Backend receives and parses packets according to ADJ specifications
+
+2. **Real-time Processing**
+   - Data validation and transformation
+   - State management and safety checks
+   - Message routing and broadcasting
+
+3. **Frontend Display**
+   - WebSocket communication for real-time updates
+   - Interactive dashboards and controls
+   - Data visualization and monitoring
+
+4. **Data Persistence**
+   - CSV logging for analysis
+   - Configuration management
+   - Historical data storage
+
+## Technology Stack
+
+### Backend
+- **Language**: Go 1.21+
+- **Networking**: TCP/UDP sockets, WebSocket (Gorilla)
+- **Packet Capture**: libpcap for network monitoring
+- **Concurrency**: Goroutines and channels for real-time processing
+
+### Frontend
+- **Framework**: React 18 with TypeScript
+- **Build Tool**: Vite
+- **State Management**: Redux Toolkit, Zustand
+- **Styling**: SCSS Modules
+- **Communication**: WebSocket, HTTP APIs
+
+### Development Tools
+- **Version Control**: Git with GitHub workflows
+- **Package Management**: Go modules, npm
+- **Build System**: Make, platform-specific scripts
+- **Testing**: Go testing, frontend unit tests
+
+## Security Considerations
+
+- Network communication validation
+- Input sanitization and validation
+- Access control for critical operations
+- Secure firmware update mechanisms
+
+## Scalability Features
+
+- Modular board management system
+- Configurable ADJ specifications
+- Plugin-based architecture for new sensors
+- Horizontal scaling capabilities
+
+## Related Documentation
+
+- [Backend Architecture](backend.md) - Detailed backend design
+- [Frontend Architecture](frontend.md) - Frontend application structure
+- [Communication Protocols](protocols.md) - Network and data protocols
+- [Development Setup](../development/DEVELOPMENT.md) - Getting started guide