Node Architecture Documents Index
Migrated from Original Docs/Node/_INDEX.md
Node Architecture Documents Index
Navigation guide to all antenna node implementation documents.
Quick Links by Role
For RF Engineers (DSP & Hardware)
Start here: Node-Hardware-Interface → Node-SourceTracking-DoA → Node-AntennaAbstraction
For Firmware & Platform Developers
Start here: Node-Architecture-Overview → Node-SoftwareProcesses-IPC → Node-ConfigurationProtocols
For Backend/API Integration
Start here: Node-NetworkPorts → Node-FrameConfig-PayloadTyping → Node-DataFlow-Timeline
For Operations & Deployment
Start here: Node-ShutdownRecovery → Node-ResourceBudgets → Node-Testing-Validation
All Documents (15 Total)
Overview & Architecture
| Document | Purpose | Audience |
|---|---|---|
| Node-Architecture-Overview | Node runtime design, five independent processes | All |
| Node-ReasoningNotes | Explicit design rationale for 3 key decisions | Decision makers |
| Node-Gaps-Deferred | Unresolved decisions (3 ADR stubs) | Architects |
Hardware & Networking
| Document | Purpose | Audience |
|---|---|---|
| Node-Hardware-Interface | RF hardware, FPGA, antenna actuation, GNSS receiver | RF engineers |
| Node-NetworkPorts | Port allocation (8080 API, 9001-9005 data ports) | Integration |
| Node-ConfigurationProtocols | Startup config, runtime HTTP API, frequency hold, Doppler compensation | Backend/Ops |
Software & Processing
| Document | Purpose | Audience |
|---|---|---|
| Node-SoftwareProcesses-IPC | Five processes (FastAPI, antenna control, DSP, router, health), IPC buses | Firmware architects |
| Node-FrameConfig-PayloadTyping | Multi-payload synchronization, pre-decode config, field typing, event output | Firmware/Backend |
| Node-DataFlow-Timeline | Lock acquisition timeline (T=0 to T=2000ms), latency targets | DSP engineers |
| Node-SourceTracking-DoA | Direction of arrival algorithms (MUSIC, ESPRIT, beam power) | RF engineers |
Antenna Control
| Document | Purpose | Audience |
|---|---|---|
| Node-AntennaAbstraction | Capability discovery, unified control interface, fallback modes | Firmware/Integration |
| Node-AntennaTypes-Deployment | Phased-array, motorized, fixed antenna characteristics & selection tree | RF/Operations |
Operations & Deployment
| Document | Purpose | Audience |
|---|---|---|
| Node-ResourceBudgets | CPU, memory, bandwidth, FPGA allocation with headroom | Ops/Architects |
| Node-ShutdownRecovery | Graceful shutdown sequence, crash recovery via systemd watchdog | Ops/Firmware |
| Node-Testing-Validation | Unit, integration, system testing procedures | QA/Test lead |
Document Outline
Node-Architecture-Overview , Start here for overview
- Node runtime design and five independent processes
- Process responsibilities and lifecycle
- Inter-process communication model
Time to read: ~15 min
Audience: Everyone
Next: Choose path by role above
Node-Hardware-Interface , For hardware integration
- RF hardware (USRP, clock, power supply)
- FPGA for beamforming and payload synchronization
- Antenna actuation hardware
- GNSS receiver for positioning and timing
Time to read: ~15 min
Audience: RF engineers, hardware integration
Depends on: Node-Architecture-Overview
Next: Node-SourceTracking-DoA or Node-AntennaAbstraction
Node-SoftwareProcesses-IPC , For process design
- Five node processes (FastAPI server, antenna controller, DSP, telemetry router, health monitor)
- Process startup order and dependencies
- IPC bus architecture (ZeroMQ, message queues)
- Error handling and process recovery
Time to read: ~20 min
Audience: Firmware architects, DevOps
Depends on: Node-Architecture-Overview
Next: Node-ConfigurationProtocols or Node-SoftwareProcesses-IPC details
Node-NetworkPorts , For network integration
- Port allocation and responsibilities:
- 8080: HTTP REST API (control & telemetry)
- 9001: Raw IQ stream (optional, high bandwidth)
- 9002: Telemetry frames and typed payloads (primary data output)
- 9003: Metrics / system health
- 9004: gRPC control (optional, future)
- 9005: Heatmap / visualization data
- Network protocol specifications
Time to read: ~10 min
Audience: Backend/integration, network ops
Depends on: Node-Architecture-Overview
Next: Node-FrameConfig-PayloadTyping or System-APIs-Contracts
Node-ConfigurationProtocols , For startup & runtime config
- Startup configuration file (JSON schema, example)
- Runtime HTTP API for config updates
- Frequency hold and Doppler compensation
- Antenna selection and parameter binding
Time to read: ~15 min
Audience: Backend devs, operations
Depends on: Node-NetworkPorts
Next: Node-FrameConfig-PayloadTyping
Node-AntennaAbstraction , For antenna control abstraction
- Capability discovery (what can this antenna do?)
- Unified control interface (common API for phased/motorized/fixed)
- Fallback modes (e.g., fixed beam if steering fails)
- Per-target antenna selection and parameter binding
Time to read: ~15 min
Audience: Firmware/backend integration
Depends on: Node-Hardware-Interface, Node-AntennaTypes-Deployment
Next: Node-ConfigurationProtocols or System-ControlDesign
Node-FrameConfig-PayloadTyping , For payload handling
- Multi-payload synchronization strategy (sync words per payload)
- Pre-decode configuration on node (raw frame bytes vs. typed payloads)
- Field type support (int, float, enum, raw bytes)
- Decoded event output shape
- Per-target payload selection
Time to read: ~20 min
Audience: Firmware/backend, DSP
Depends on: Node-ConfigurationProtocols
Next: Node-DataFlow-Timeline
Node-DataFlow-Timeline , For latency analysis
- Lock acquisition timeline: T=0 (frame sync) to T=2000ms (telemetry availability)
- Each stage (frame sync, FPGA analysis, Python DSP, telecom latency) with latency targets
- Bottleneck identification and optimization strategies
Time to read: ~15 min
Audience: DSP engineers, performance architects
Depends on: Node-FrameConfig-PayloadTyping
Next: Node-SourceTracking-DoA
Node-SourceTracking-DoA , For signal processing algorithms
- Direction of arrival (DoA) estimation methods:
- MUSIC (Multiple Signal Classification)
- ESPRIT (Estimation of Signal Parameters via Rotational Invariance)
- Beam power maximization
- When to use each method, accuracy expectations
- Integration with antenna array
Time to read: ~15 min
Audience: RF/DSP engineers
Depends on: Node-DataFlow-Timeline
Next: Node-AntennaTypes-Deployment
Node-AntennaTypes-Deployment , For antenna selection
- Antenna type characteristics:
- Phased-array (electronic steering, 10-50°/sec, 15-20dBi)
- Motorized parabolic (mechanical, 1-10°/sec, 25-30dBi)
- Fixed (no actuation, fallback)
- Deployment decision tree (pointing required? speed? gain?)
- Compatibility with DoA algorithms
Time to read: ~15 min
Audience: RF engineers, operations
Depends on: Node-Hardware-Interface, Node-SourceTracking-DoA
Next: Node-ResourceBudgets
Node-ResourceBudgets , For capacity planning
- CPU allocation by process (%, headroom)
- Memory allocation by process (GB, headroom)
- Network bandwidth allocation (Mbps per port)
- FPGA resource usage (LUTs, BRAM, DSP slices)
Time to read: ~10 min
Audience: Ops/architects, performance
Depends on: Node-SoftwareProcesses-IPC
Next: Node-Testing-Validation
Node-ShutdownRecovery , For operational reliability
- Graceful shutdown sequence (stop decoding, flush buffers, save state)
- Crash recovery using systemd watchdog
- Data consistency (frame buffer durability)
- Restart procedures
Time to read: ~15 min
Audience: Operations, firmware
Depends on: Node-SoftwareProcesses-IPC
Next: Node-Testing-Validation
Node-Testing-Validation , For QA & deployment
- Unit testing (per-process tests, mocking)
- Integration testing (IPC correctness, multi-process interaction)
- System testing (end-to-end signal acquisition, decoding, output)
- Field validation procedures
Time to read: ~15 min
Audience: QA/test lead, firmware
Depends on: All prior docs (testing validates full node)
Next: Deployment and operations
Node-ReasoningNotes , Design decisions explained
- Why decode toggles are on node API (flexibility vs. central push)
- Why typed decoding + raw export coexist (forensic safety, fallback)
- Why target identity is preserved but not interpreted (RF/mission separation)
Time to read: ~10 min
Audience: Decision makers, skeptical stakeholders
Depends on: Node-Architecture-Overview
Next: Understanding trade-offs in other docs
Node-Gaps-Deferred , Unresolved decisions (3 ADRs)
- N-ADR-001: Schema Validation Strictness
- N-ADR-002: Decoder Backpressure Policy
- N-ADR-003: GNSS Degradation & Timestamp Authority
Time to read: ~10 min (scan only)
Audience: Architects, decision makers
Depends on: All prior docs
Next: ADR Index for full ADR details
Recommended Reading Paths
Path 1: Complete Node Understanding (2-3 hours)
- Node-Architecture-Overview (15 min)
- Node-Hardware-Interface (15 min)
- Node-SoftwareProcesses-IPC (20 min)
- Node-NetworkPorts (10 min)
- Node-ConfigurationProtocols (15 min)
- Node-FrameConfig-PayloadTyping (20 min)
- Node-DataFlow-Timeline (15 min)
- Node-ResourceBudgets (10 min)
- Node-ShutdownRecovery (15 min)
Total: ~2 hours
Audience: New team members, architects
Path 2: Firmware Implementation (1.5 hours)
- Node-Architecture-Overview (15 min)
- Node-SoftwareProcesses-IPC (20 min)
- Node-ConfigurationProtocols (15 min)
- Node-FrameConfig-PayloadTyping (20 min)
- Node-ShutdownRecovery (15 min)
- Node-Testing-Validation (15 min)
Total: ~1.5 hours
Audience: Firmware developers
Path 3: RF Engineering (1.5 hours)
- Node-Architecture-Overview (15 min)
- Node-Hardware-Interface (15 min)
- Node-DataFlow-Timeline (15 min)
- Node-SourceTracking-DoA (20 min)
- Node-AntennaTypes-Deployment (15 min)
Total: ~1.5 hours
Audience: RF engineers, signal processing
Path 4: Backend/Integration (1 hour)
- Node-Architecture-Overview (15 min)
- Node-NetworkPorts (10 min)
- Node-ConfigurationProtocols (15 min)
- Node-FrameConfig-PayloadTyping (15 min)
- Node-DataFlow-Timeline (10 min)
Total: ~1 hour
Audience: Backend developers, integration
Path 5: Operations & Deployment (1 hour)
- Node-Architecture-Overview (15 min)
- Node-ResourceBudgets (10 min)
- Node-ShutdownRecovery (15 min)
- Node-Testing-Validation (15 min)
- Node-ConfigurationProtocols (5 min)
Total: ~1 hour
Audience: Operations, DevOps
Cross-References
By Topic:
- Hardware Integration: Node-Hardware-Interface → Node-AntennaAbstraction
- Process Architecture: Node-SoftwareProcesses-IPC → Node-ShutdownRecovery
- Real-time Processing: Node-DataFlow-Timeline → Node-SourceTracking-DoA
- Antenna Control: Node-AntennaAbstraction → Node-AntennaTypes-Deployment
- Payload Management: Node-FrameConfig-PayloadTyping → Node-ConfigurationProtocols
Critical Decision Points:
- Schema Validation: N-ADR-001-SchemaValidation
- Decoder Backpressure: N-ADR-002-Decoder-Backpressure
- Timestamp Authority: N-ADR-003-GNSS-Degradation
Links to Ground Station Architecture:
- Control Integration: Ground Station Frontend + Ground Station Control Surface Design
- API Contracts: Shared APIs & Contracts
- Central Aggregator: Ground Station Central Aggregator
Navigation Legend
- 15 documents: Node implementation fully specified
- ~7500+ lines: Total extracted from original monolithic document
- Organized by: Concern (hardware, processes, testing) and audience
- Linked to: Ground Station architecture (Ground Station) and ADRs (ADR Index)
Return to: Project Overview | ADR Index | Ground Station