Skip to content

System Architecture

Jump to bottom
Marc Sanchis edited this page Jun 5, 2025 · 1 revision

System Architecture

Comprehensive overview of the Hyperloop UPV Control Station architecture, components, and design principles.

🏗️ High-Level Architecture

The Control Station follows a distributed, real-time architecture designed for safety, reliability, and scalability.

System Overview

┌─────────────────────────────────────────────────────────────────────┐
│                     Hyperloop UPV Control Station                   │
├─────────────────────┬───────────────────────┬─────────────────────┤
│   Frontend Layer    │    Backend Layer      │   Hardware Layer    │
│                     │                       │                     │
│  ┌───────────────┐  │  ┌─────────────────┐  │  ┌───────────────┐  │
│  │ Control       │  │  │                 │  │  │ Pod Sensors   │  │
│  │ Station       │◄─┼─►│   Go Backend    │◄─┼─►│ & Boards      │  │
│  │ (React)       │  │  │   Server        │  │  │               │  │
│  └───────────────┘  │  │                 │  │  └───────────────┘  │
│                     │  │ ┌─────────────┐ │  │                     │
│  ┌───────────────┐  │  │ │ WebSocket   │ │  │  ┌───────────────┐  │
│  │ Ethernet      │  │  │ │ Server      │ │  │  │ Network       │  │
│  │ View          │◄─┼─►│ └─────────────┘ │◄─┼─►│ Infrastructure│  │
│  │ (React)       │  │  │                 │  │  │               │  │
│  └───────────────┘  │  │ ┌─────────────┐ │  │  └───────────────┘  │
│                     │  │ │ Data Logger │ │  │                     │
│  ┌───────────────┐  │  │ │ & Storage   │ │  │  ┌───────────────┐  │
│  │ Common        │  │  │ └─────────────┘ │  │  │ TFTP Servers  │  │
│  │ Components    │  │  └─────────────────┘  │  │ (Firmware)    │  │
│  │ (Library)     │  │                       │  └───────────────┘  │
│  └───────────────┘  │                       │                     │
└─────────────────────┴───────────────────────┴─────────────────────┘

🎯 Design Principles

1. Real-Time Performance

  • Sub-millisecond response for critical operations
  • Concurrent processing using Go goroutines
  • Efficient data structures for high-throughput scenarios
  • Memory-mapped I/O for optimal performance

2. Safety and Reliability

  • Fail-safe design with automatic fallbacks
  • Comprehensive error handling and recovery
  • Data validation at every layer
  • Redundant communication paths

3. Modularity and Scalability

  • Microservice-like backend components
  • Plugin-based board management
  • Configurable ADJ specifications
  • Horizontal scaling capabilities

4. Cross-Platform Compatibility

  • Native builds for Windows, macOS, and Linux
  • Container support for deployment flexibility
  • Consistent APIs across platforms

🖥️ Frontend Architecture

Component Structure

Frontend Applications
├── common-front/           # Shared component library
│   ├── components/         # Reusable UI components
│   ├── hooks/             # Custom React hooks  
│   ├── stores/            # State management
│   ├── adapters/          # Data transformation
│   └── services/          # Business logic
│
├── control-station/       # Main operational interface
│   ├── pages/            # Route components
│   ├── components/       # App-specific components
│   └── assets/           # Static resources
│
└── ethernet-view/         # Network debugging interface
    ├── components/       # Network monitoring UI
    ├── services/         # Network analysis logic
    └── utils/            # Utility functions

Technology Stack

Layer Technology Purpose
Framework React 18 Component-based UI
Language TypeScript Type safety and developer experience
Build Tool Vite Fast development and building
State Management Redux Toolkit, Zustand Global and local state
Styling SCSS Modules Component-scoped styling
Communication WebSocket, Fetch API Real-time and HTTP communication

Data Flow

User Interaction → Component → Hook → Store → WebSocket → Backend
                                 ↓
User Interface ← Component ← Hook ← Store ← WebSocket ← Backend

⚙️ Backend Architecture

Core Components

Backend Server (Go)
├── cmd/                   # Application entry point
│   ├── main.go           # Server initialization
│   ├── config.go         # Configuration management
│   └── adj/              # ADJ specifications
│
├── pkg/                  # Core packages
│   ├── transport/        # Network communication
│   ├── broker/           # Message routing
│   ├── vehicle/          # Pod management
│   ├── boards/           # Board abstractions
│   ├── logger/           # Data logging
│   └── websocket/        # WebSocket handling
│
└── internal/             # Internal utilities
    ├── common/           # Shared utilities
    ├── pod_data/         # Pod data models
    └── update_factory/   # Update management

Package Responsibilities

Transport Layer (pkg/transport/)

  • TCP/UDP communication with pod boards
  • Packet parsing and validation
  • Protocol abstraction
  • Network error handling

Broker System (pkg/broker/)

  • Message routing between components
  • Topic-based communication
  • WebSocket client management
  • Request/response handling

Vehicle Management (pkg/vehicle/)

  • Pod state coordination
  • Board lifecycle management
  • Safety monitoring
  • Command dispatching

Board Abstractions (pkg/boards/)

  • Individual board handlers
  • BLCU firmware management
  • Board-specific protocols
  • Status monitoring

Concurrency Model

Main Goroutine
├── HTTP Server Goroutine
├── WebSocket Pool Goroutine
├── Transport Handlers
│   ├── TCP Client Goroutines (per board)
│   ├── TCP Server Goroutine
│   └── Packet Sniffer Goroutine
├── Broker Workers
│   ├── Topic Handlers (per topic)
│   └── Message Router Goroutine
└── Logger Goroutines (per log type)

🗄️ Data Architecture

Data Flow Pipeline

Pod Sensors → Ethernet → Backend Parser → Data Validation → 
Business Logic → State Updates → WebSocket → Frontend Display
                    ↓
                Data Logger → CSV Files → Analysis Tools

Data Models

Measurement Data

type Measurement struct {
    ID        uint16    `json:"id"`
    Name      string    `json:"name"`
    Value     float64   `json:"value"`
    Unit      string    `json:"unit"`
    Timestamp time.Time `json:"timestamp"`
    BoardID   string    `json:"board_id"`
}

Board Configuration

type Board struct {
    Name        string        `json:"name"`
    ID          uint16        `json:"id"`
    Address     string        `json:"address"`
    Packets     []PacketSpec  `json:"packets"`
    Orders      []OrderSpec   `json:"orders"`
}

Network Packet

type Packet struct {
    ID        uint16    `json:"id"`
    Timestamp time.Time `json:"timestamp"`
    Data      []byte    `json:"data"`
    Source    string    `json:"source"`
    BoardID   string    `json:"board_id"`
}

🌐 Network Architecture

Physical Network Topology

Control Station (192.168.0.0/24)
        ↕ (Ethernet + WiFi backup)
    Router/Switch
        ↕ (NAP Wireless Bridge)
Vehicle Network (192.168.1.0/24)
        ↕ (NAP Wireless Bridge)
Booster Network (192.168.2.0/24)

Protocol Stack

Layer Protocol Purpose
Application WebSocket, HTTP, TFTP User interface and file transfer
Transport TCP, UDP Reliable and fast communication
Network IPv4 Internet protocol
Data Link Ethernet, WiFi Physical connectivity
Physical Cat6, 5GHz Radio Hardware layer

Communication Patterns

Real-Time Data Streaming

  • UDP multicast for sensor data
  • WebSocket for frontend updates
  • Binary protocols for efficiency

Command and Control

  • TCP for reliable order delivery
  • Acknowledgment patterns for safety
  • Timeout and retry mechanisms

File Operations

  • TFTP for firmware updates
  • HTTP for configuration files
  • WebSocket for progress updates

🔒 Security Architecture

Multi-Layer Security

┌─────────────────────────────────────────┐
│           Security Layers               │
├─────────────────────────────────────────┤
│ 7. Application Security                 │
│    • Input validation                   │
│    • Authentication & authorization     │
├─────────────────────────────────────────┤
│ 6. Data Security                        │
│    • Encryption at rest                 │
│    • Secure data transmission           │
├─────────────────────────────────────────┤
│ 5. Network Security                     │
│    • WPA2 encryption                    │
│    • Network segmentation               │
├─────────────────────────────────────────┤
│ 4. System Security                      │
│    • OS hardening                       │
│    • Service isolation                  │
├─────────────────────────────────────────┤
│ 3. Physical Security                    │
│    • Secure hardware access             │
│    • Cable management                   │
└─────────────────────────────────────────┘

Security Features

  • Network Isolation: Separate VLANs for different systems
  • Access Control: Role-based permissions
  • Data Validation: Input sanitization and validation
  • Secure Communication: TLS/SSL for sensitive data
  • Audit Logging: Comprehensive security event logging

📊 Performance Characteristics

Latency Requirements

Operation Target Latency Maximum Latency
Sensor Data Display < 100ms 200ms
Emergency Commands < 50ms 100ms
Status Updates < 200ms 500ms
File Operations N/A 30s

Throughput Specifications

Data Type Rate Bandwidth
Sensor Data 1000 measurements/sec ~100 KB/s
Video Streams 30 FPS ~5 MB/s
Command Traffic 10 commands/sec ~1 KB/s
Log Data 100 entries/sec ~10 KB/s

Scalability Metrics

  • Concurrent Users: 10+ operators
  • Board Support: 20+ boards simultaneously
  • Data Retention: 30+ days of logs
  • Network Nodes: 50+ devices

🔧 Configuration Management

ADJ (Board Specification) System

The ADJ system provides dynamic configuration for:

# Example ADJ Structure
boards:
  VCU:
    id: 0x01
    address: "192.168.1.101"
    packets:
      - id: 0x100
        name: "speed_measurement"
        fields: ["speed", "acceleration"]
    orders:
      - id: 0x200
        name: "emergency_brake"
        fields: ["force_level"]

measurements:
  speed:
    unit: "m/s"
    range: [0, 150]
    precision: 0.1

Environment Configuration

# config.toml
[network]
backend_ip = "192.168.0.9"
backend_port = 8080

[vehicle.boards]
VCU = true
PCU = true
TCU = true
BLCU = true

[adj]
branch = "main"
auto_update = true

🚀 Deployment Architecture

Development Environment

  • Local development with hot reloading
  • Mock data sources for testing
  • Containerized services for consistency

Testing Environment

  • Automated testing with CI/CD
  • Integration testing with real hardware
  • Performance testing under load

Production Environment

  • High availability deployment
  • Load balancing for multiple instances
  • Monitoring and alerting
  • Backup and recovery systems

🔗 Integration Points

External Systems

  • Pod Vehicle Networks: Real-time sensor integration
  • Safety Systems: Emergency shutdown integration
  • Timing Systems: Competition timing integration
  • Data Analysis: Post-processing and analytics

APIs and Interfaces

  • REST API: Configuration and status queries
  • WebSocket API: Real-time data streaming
  • TFTP Interface: Firmware management
  • File System: Log and configuration management

📈 Monitoring and Observability

System Metrics

  • Performance metrics: Latency, throughput, error rates
  • Resource utilization: CPU, memory, network, disk
  • Business metrics: Operations completed, data quality
  • Security metrics: Access attempts, anomalies

Logging Strategy

  • Structured logging with consistent formats
  • Log levels: Debug, Info, Warn, Error, Fatal
  • Log aggregation for analysis
  • Real-time monitoring and alerting

🔗 Related Documentation

🏗️ Architecture Overview Complete

This system architecture provides the foundation for safe, reliable, and high-performance hyperloop pod operations. For detailed implementation guides, explore the related documentation links above.

Clone this wiki locally