|
1 | | -# System Architecture Overview |
| 1 | +# System Architecture |
2 | 2 |
|
3 | | -The Hyperloop H10 Control Station is a real-time monitoring and control system designed for managing pod operations during testing and competition runs. |
| 3 | +The Hyperloop UPV Control Station is a real-time monitoring and control system for pod operations. |
4 | 4 |
|
5 | | -## High-Level Architecture |
| 5 | +## Quick Links |
| 6 | +- 📖 **[Complete Architecture Guide](../../CONTROL_STATION_COMPLETE_ARCHITECTURE.md)** - Comprehensive system documentation |
| 7 | +- 🔄 **[Packet Flow Reference](packet-flow-reference.md)** - Quick reference for data flow |
| 8 | +- 📡 **[Communication Protocols](protocols.md)** - Network protocol specifications |
| 9 | +- 🐛 **[Known Issues](issues-and-improvements.md)** - Current limitations and roadmap |
| 10 | + |
| 11 | +## Overview |
6 | 12 |
|
7 | 13 | ``` |
8 | 14 | ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ |
| 15 | +│ Pod Boards │◄──►│ Backend (Go) │◄──►│ Frontend (React)│ |
9 | 16 | │ │ │ │ │ │ |
10 | | -│ Pod Sensors │◄──►│ Backend │◄──►│ Frontend │ |
11 | | -│ & Boards │ │ (Go Server) │ │ (React Apps) │ |
12 | | -│ │ │ │ │ │ |
| 17 | +│ • Sensors │ │ • TCP/UDP │ │ • Control UI │ |
| 18 | +│ • Actuators │ │ • Processing │ │ • Monitoring │ |
| 19 | +│ • Controllers │ │ • WebSocket │ │ • Logging │ |
13 | 20 | └─────────────────┘ └─────────────────┘ └─────────────────┘ |
14 | | - │ |
15 | | - ▼ |
16 | | - ┌─────────────────┐ |
17 | | - │ │ |
18 | | - │ Data Logger │ |
19 | | - │ & Storage │ |
20 | | - │ │ |
21 | | - └─────────────────┘ |
| 21 | + ▲ │ ▲ |
| 22 | + │ ▼ │ |
| 23 | + │ ┌─────────────────┐ │ |
| 24 | + └────────────│ ADJ Config │──────────────┘ |
| 25 | + │ (JSON specs) │ |
| 26 | + └─────────────────┘ |
22 | 27 | ``` |
23 | 28 |
|
24 | 29 | ## Core Components |
25 | 30 |
|
26 | | -### 1. Backend (Go) |
27 | | -- **Location**: `backend/` |
28 | | -- **Purpose**: Real-time data processing and communication hub |
29 | | -- **Key Features**: |
30 | | - - TCP/UDP packet processing |
31 | | - - WebSocket server for frontend communication |
32 | | - - TFTP server for firmware updates |
33 | | - - Data logging and storage |
34 | | - - Board abstraction and management |
35 | | - |
36 | | -### 2. Frontend Applications (React/TypeScript) |
37 | | -- **Common Frontend**: `common-front/` - Shared component library |
38 | | -- **Control Station**: `control-station/` - Main operational interface |
39 | | -- **Ethernet View**: `ethernet-view/` - Network debugging and monitoring |
40 | | - |
41 | | -### 3. Supporting Tools |
42 | | -- **Packet Sender**: `packet-sender/` - Testing and simulation tool |
43 | | -- **Updater**: `updater/` - System update management |
44 | | -- **Scripts**: `scripts/` - Development and deployment automation |
45 | | - |
46 | | -## Data Flow |
47 | | - |
48 | | -1. **Sensor Data Collection** |
49 | | - - Pod sensors send data via Ethernet/TCP |
50 | | - - Backend receives and parses packets according to ADJ specifications |
51 | | - |
52 | | -2. **Real-time Processing** |
53 | | - - Data validation and transformation |
54 | | - - State management and safety checks |
55 | | - - Message routing and broadcasting |
56 | | - |
57 | | -3. **Frontend Display** |
58 | | - - WebSocket communication for real-time updates |
59 | | - - Interactive dashboards and controls |
60 | | - - Data visualization and monitoring |
61 | | - |
62 | | -4. **Data Persistence** |
63 | | - - CSV logging for analysis |
64 | | - - Configuration management |
65 | | - - Historical data storage |
| 31 | +### Backend (Go) |
| 32 | +High-performance server managing real-time communication and data processing. |
| 33 | +- **Location**: [`backend/`](../../backend) |
| 34 | +- **Key Features**: Concurrent packet processing, automatic reconnection, sub-10ms response time |
| 35 | +- **Documentation**: [Backend Architecture](backend.md) |
66 | 36 |
|
67 | | -## Technology Stack |
| 37 | +### Frontend (React/TypeScript) |
| 38 | +Modern web interfaces for system monitoring and control. |
| 39 | +- **Locations**: [`control-station/`](../../control-station), [`ethernet-view/`](../../ethernet-view) |
| 40 | +- **Key Features**: Real-time updates, interactive controls, data visualization |
| 41 | +- **Documentation**: [Frontend Architecture](frontend.md) |
68 | 42 |
|
69 | | -### Backend |
70 | | -- **Language**: Go 1.21+ |
71 | | -- **Networking**: TCP/UDP sockets, WebSocket (Gorilla) |
72 | | -- **Packet Capture**: libpcap for network monitoring |
73 | | -- **Concurrency**: Goroutines and channels for real-time processing |
| 43 | +### ADJ System |
| 44 | +JSON-based configuration defining all communication specifications. |
| 45 | +- **Location**: [`adj/`](https://github.com/HyperloopUPV-H8/adj) (external repository) |
| 46 | +- **Purpose**: Board definitions, packet structures, unit conversions |
| 47 | +- **Documentation**: [ADJ Specification](../../backend/internal/adj/README.md) |
74 | 48 |
|
75 | | -### Frontend |
76 | | -- **Framework**: React 18 with TypeScript |
77 | | -- **Build Tool**: Vite |
78 | | -- **State Management**: Redux Toolkit, Zustand |
79 | | -- **Styling**: SCSS Modules |
80 | | -- **Communication**: WebSocket, HTTP APIs |
| 49 | +## Key Capabilities |
81 | 50 |
|
82 | | -### Development Tools |
83 | | -- **Version Control**: Git with GitHub workflows |
84 | | -- **Package Management**: Go modules, npm |
85 | | -- **Build System**: Make, platform-specific scripts |
86 | | -- **Testing**: Go testing, frontend unit tests |
| 51 | +- **Real-time Performance**: 100+ Mbps data processing, <10ms fault detection |
| 52 | +- **Modular Design**: Board-agnostic architecture using ADJ specifications |
| 53 | +- **Fault Tolerance**: Automatic reconnection, graceful degradation |
| 54 | +- **Scalability**: Supports 10+ concurrent board connections |
87 | 55 |
|
88 | | -## Security Considerations |
| 56 | +## Technology Stack |
89 | 57 |
|
90 | | -- Network communication validation |
91 | | -- Input sanitization and validation |
92 | | -- Access control for critical operations |
93 | | -- Secure firmware update mechanisms |
| 58 | +| Component | Technology | Purpose | |
| 59 | +|-----------|------------|---------| |
| 60 | +| Backend | Go 1.21+ | High-performance networking and concurrency | |
| 61 | +| Frontend | React 18 + TypeScript | Type-safe UI development | |
| 62 | +| Communication | WebSocket | Real-time bidirectional updates | |
| 63 | +| Configuration | JSON (ADJ) | Flexible system specification | |
| 64 | +| Networking | TCP/UDP/TFTP | Reliable and fast data transfer | |
94 | 65 |
|
95 | | -## Scalability Features |
| 66 | +## Documentation Index |
96 | 67 |
|
97 | | -- Modular board management system |
98 | | -- Configurable ADJ specifications |
99 | | -- Plugin-based architecture for new sensors |
100 | | -- Horizontal scaling capabilities |
| 68 | +### Architecture Details |
| 69 | +- [Backend Architecture](backend.md) - Go server design and implementation |
| 70 | +- [Frontend Architecture](frontend.md) - React application structure |
| 71 | +- [Binary Protocol](binary-protocol.md) - Wire protocol specification |
| 72 | +- [WebSocket API](websocket-api.md) - Frontend-backend communication |
101 | 73 |
|
102 | | -## Communication Protocols |
| 74 | +### Development Resources |
| 75 | +- [Getting Started](../guides/getting-started.md) - New developer guide |
| 76 | +- [Development Setup](../development/DEVELOPMENT.md) - Environment configuration |
| 77 | +- [Troubleshooting](../troubleshooting/common-issues.md) - Common problems |
103 | 78 |
|
104 | | -Comprehensive documentation for all communication layers: |
| 79 | +## Next Steps |
105 | 80 |
|
106 | | -- [**Protocols Overview**](./protocols.md) - High-level communication architecture |
107 | | -- [**Message Structures**](./message-structures.md) - Complete message format specifications |
108 | | -- [**Binary Protocol**](./binary-protocol.md) - Vehicle ↔ Backend wire protocol |
109 | | -- [**WebSocket API**](./websocket-api.md) - Backend ↔ Frontend API specification |
| 81 | +- **New to the project?** Start with the [Getting Started Guide](../guides/getting-started.md) |
| 82 | +- **Understanding data flow?** Read the [Complete Architecture Guide](../../CONTROL_STATION_COMPLETE_ARCHITECTURE.md) |
| 83 | +- **Debugging issues?** Check [Troubleshooting](../troubleshooting/common-issues.md) |
| 84 | +- **Contributing?** Review [Known Issues](issues-and-improvements.md) for areas needing help |
110 | 85 |
|
111 | | -## Related Documentation |
| 86 | +--- |
112 | 87 |
|
113 | | -- [Backend Architecture](backend.md) - Detailed backend design |
114 | | -- [Frontend Architecture](frontend.md) - Frontend application structure |
115 | | -- [Development Setup](../development/DEVELOPMENT.md) - Getting started guide |
| 88 | +*For the complete technical deep-dive, see the [Control Station Complete Architecture](../../CONTROL_STATION_COMPLETE_ARCHITECTURE.md) document.* |
0 commit comments