From 8ed0df3dce9a5344780dd971ebf97fbd7da2e37f Mon Sep 17 00:00:00 2001 From: Mike Kell Date: Tue, 21 Jul 2026 08:00:18 -0400 Subject: [PATCH] feat: initialize documentation structure and CI workflow --- .github/workflows/validate-docs.yaml | 38 ++++++++ .gitignore | 4 + README.md | 33 +++++++ docs/architecture/01_system_architecture.md | 52 ++++++++++ .../architecture/workspace/sync_sequence.puml | 28 ++++++ docs/index.md | 10 ++ docs/protocols/02_api_and_protocols.md | 94 +++++++++++++++++++ docs/security/03_security_and_defense.md | 39 ++++++++ docs/workflows/04_workflows_and_crdt.md | 49 ++++++++++ mkdocs.yml | 20 ++++ 10 files changed, 367 insertions(+) create mode 100644 .github/workflows/validate-docs.yaml create mode 100644 .gitignore create mode 100644 README.md create mode 100644 docs/architecture/01_system_architecture.md create mode 100644 docs/architecture/workspace/sync_sequence.puml create mode 100644 docs/index.md create mode 100644 docs/protocols/02_api_and_protocols.md create mode 100644 docs/security/03_security_and_defense.md create mode 100644 docs/workflows/04_workflows_and_crdt.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/validate-docs.yaml b/.github/workflows/validate-docs.yaml new file mode 100644 index 0000000..2165f3c --- /dev/null +++ b/.github/workflows/validate-docs.yaml @@ -0,0 +1,38 @@ +name: Validate Docs + +on: + push: + branches: + - '**' + - '!main' + +jobs: + validate-docs: + runs-on: docs-host + + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + + - name: Render PlantUML diagrams to SVG + run: | + mkdir -p docs/images + docker run --rm \ + -v "$PWD:/work" \ + -w /work \ + ghcr.io/plantuml/plantuml \ + -tsvg docs/architecture/workspace/*.puml + cp docs/architecture/workspace/*.svg docs/images/ + + - name: Build MkDocs Site + run: | + docker run --rm \ + -v "$PWD:/docs" \ + squidfunk/mkdocs-material:9 \ + build + + - name: Validate Expected Output + run: | + test -f site/index.html + test -d site/architecture + echo "MkDocs validation passed" \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a06f30d --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +.vscode/ +site/ +*.tmp +*.log diff --git a/README.md b/README.md new file mode 100644 index 0000000..4c680ba --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +# Technical Design Documentation: US Army Signal Transport Planning & Operations Tool + +Welcome to the central design repository for the US Army Signal Transport Planning & Operations Tool. These design specifications establish the core system architecture, network transport protocols, security models, and synchronization mechanisms for software development. + +## Documentation Index + +1. [System Architecture & Resource Profile](architecture/01_system_architecture.md) + * High-level system design and client targets (Tactical Web vs. Android Edge). + * Resource overhead budgets (CPU, RAM, storage, network). + * Technology stack selection and compute optimizations. + +2. [API & Data Protocols Specification](protocols/02_api_and_protocols.md) + * Serialization standards (Protocol Buffers v3). + * gRPC interface definitions for telemetry, spectrum streaming, and AI recommendations. + * `transport_engine.proto` complete schema design. + +3. [Security Architecture & Defensive Modeling](security/03_security_and_defense.md) + * Full OSI Layer 1 through Layer 7 defensive mechanisms. + * Role-Based and Attribute-Based Access Control (RBAC/ABAC) permission hierarchy. + * Zero Trust authentication and transport encryption standards. + +4. [Signal Workflows & CRDT Synchronization Engine](workflows/04_workflows_and_crdt.md) + * 6-phase Signal Lifecycle Workflow (Engineering through Governance/AAR). + * Offline peer-to-peer synchronization architecture. + * Conflict-Free Replicated Data Type (CRDT) deterministic resolution rules. + +--- + +## Quick Reference +* **Core Runtime:** C++20 (NDK / WebAssembly) +* **Serialization:** Protocol Buffers v3 / gRPC +* **Sync Strategy:** LWW-Element-Set CRDT over UDP/DTN +* **Primary Target Environments:** Android Tactical Tablets (Dismounted) & Tactical Web (Command Post) diff --git a/docs/architecture/01_system_architecture.md b/docs/architecture/01_system_architecture.md new file mode 100644 index 0000000..5776ae7 --- /dev/null +++ b/docs/architecture/01_system_architecture.md @@ -0,0 +1,52 @@ +# Architectural Specification: US Army Signal Transport Planning & Operations Tool + +## 1. System Overview & Operational Context +This document defines the system design for the US Army Signal Transport Planning & Operations Tool. The application provides continuous link engineering, spectrum deconfliction, network topology modeling, and real-time operational monitoring across Disconnected, Intermittent, and Limited-Bandwidth (DDIL) tactical environments. + +### Operational Deployment Targets +1. **Command Post Web Client (Tactical Web):** Hosted locally within a Tactical Micro-Cloud or CPCE (Command Post Computing Environment) server node. Designed for high-density multi-link visualization, automated frequency spectrum planning, and global readiness tracking. +2. **Dismounted Tactical Edge Client (Android Tablet):** Native Android deployment executing on tactical ruggedized tablets (e.g., Samsung Active Tab / Nett Warrior handhelds). Focused on local node configuration, line-of-sight elevation checks, hardware cut-sheet generation, and offline CRDT sync. + +--- + +## 2. High-Level System Architecture Diagram + +``` ++-----------------------------------------------------------------------------------+ +| TACTICAL USER INTERFACE | +| Tactical Web (PWA / Wasm Engine) | Android Tactical Tablet (Kotlin / NDK) | ++---------------------------------------+-------------------------------------------+ + | + [ Local State ] + SQLite / Room DB + Vector Tile Cache + | + [ Local gRPC / Protobuf Engine ] + | + +-----------------------------------+-----------------------------------+ + | | | +[ P2P Mesh Sync ] [ Store-and-Forward ] [ Agentic AI Bus ] + (Direct Tactical Wi-Fi / (Delay-Tolerant Networking / (Lightweight Inference / + Bluetooth / Tactical RF) Protocol Buffers over UDP) On-Device C++ Core) +``` + +--- + +## 3. Resource Budget & Memory Constraints + +| Parameter | Command Post Web Client | Android Tactical Edge Client | +| :--- | :--- | :--- | +| **Max Memory Overhead** | $\le 1.5\text{ GB}$ RAM | $\le 450\text{ MB}$ RAM | +| **Target CPU Allocation** | $< 15\%$ Idle / $< 60\%$ Active Terrain Computation | $< 5\%$ Idle / $< 30\%$ Active Terrain Computation | +| **Storage Cap** | $\le 10\text{ GB}$ Map Vector Tiles & Session Log | $\le 2\text{ GB}$ Region Pruned Map Tiles & Mission State | +| **Network Overhead** | Full State Delta Sync over High-Bandwidth LAN/SATCOM | Compressed Protobuf Binary Payloads over RF Waveforms | +| **Compute Engine** | C++ Compiled to WebAssembly (Wasm) | Native C++20 Shared Object via JNI / Android NDK | + +--- + +## 4. Technology Stack Matrix + +* **Core Engine:** C++20 (CMake, Emscripten for Wasm compilation). +* **Android Client:** Kotlin, Android Jetpack (Compose, Room, WorkManager), NDK / JNI Bridge. +* **Web Client:** TypeScript, React, WebGL vector tile renderer, WebAssembly loader. +* **Data Layer & Storage:** SQLite3 with R-Tree spatial indexing plugin (`MBTiles` format). +* **Network & Serialization:** Protocol Buffers v3, gRPC, gRPC-Web, Custom DTN (Delay-Tolerant Networking) bundle transport over UDP. diff --git a/docs/architecture/workspace/sync_sequence.puml b/docs/architecture/workspace/sync_sequence.puml new file mode 100644 index 0000000..35f95ee --- /dev/null +++ b/docs/architecture/workspace/sync_sequence.puml @@ -0,0 +1,28 @@ +@startuml +skinparam Monochrome true +skinparam Shadowing false + +actor "Signal Planner (Node Alpha)" as Alpha +participant "Local State (Node Alpha)" as StateA +participant "CRDT Sync Engine" as SyncEngine +participant "Local State (Node Bravo)" as StateB +actor "Network Engineer (Node Bravo)" as Bravo + +Alpha -> StateA: Modify Link Freq (420 MHz)\n[HLC: {T: 100, Counter: 1, Node: A}] +Bravo -> StateB: Modify Link Freq (425 MHz)\n[HLC: {T: 100, Counter: 2, Node: B}] + +note over SyncEngine + Intermittent Tactical Link Connection Restored +end note + +StateA -> SyncEngine: Push Delta Payload (Protobuf)\n[Vector Clock & RBAC Signature: Signal Planner] +StateB -> SyncEngine: Push Delta Payload (Protobuf)\n[Vector Clock & RBAC Signature: Network Engineer] + +SyncEngine -> SyncEngine: Evaluate Conflict Resolution:\n1. Check RBAC Tier (Signal Planner > Network Engineer)\n2. Compare Hybrid Logical Clock (HLC) + +SyncEngine -> StateA: Apply Winner State (420 MHz) +SyncEngine -> StateB: Apply Winner State (420 MHz) + +StateA --> Alpha: State Converged (420 MHz) +StateB --> Bravo: State Converged (420 MHz) +@enduml diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..d5a4365 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,10 @@ +# US Army Signal Transport Planning & Operations Tool + +Welcome to the central technical documentation site for the US Army Signal Transport Planning & Operations Tool. This documentation provides complete architectural specifications, API schemas, security frameworks, and workflow designs. + +## Documentation Structure + +* [System Architecture](architecture/01_system_architecture.md): Compute profiles, memory targets, and client runtimes. +* [API & Protocols](protocols/02_api_and_protocols.md): Protocol Buffer v3 definitions and gRPC service interfaces. +* [Security & Defense](security/03_security_and_defense.md): Zero Trust architecture, OSI L1-L7 security stack, and RBAC rules. +* [Workflows & CRDT](workflows/04_workflows_and_crdt.md): Signal lifecycle workflow and multi-user offline CRDT synchronization engine. diff --git a/docs/protocols/02_api_and_protocols.md b/docs/protocols/02_api_and_protocols.md new file mode 100644 index 0000000..187c152 --- /dev/null +++ b/docs/protocols/02_api_and_protocols.md @@ -0,0 +1,94 @@ +# API Protocol & Data Schema Specification + +## 1. Data Serialization Standards +All inter-node synchronization, local state persistence, and AI agent communications utilize **Protocol Buffers v3** with **zstd compression** over binary gRPC streams or raw UDP transport. + +--- + +## 2. Protocol Buffer Schemas (`transport_engine.proto`) + +```protobuf +syntax = "proto3"; + +package usarmy.signal.transport.v1; + +option go_package = "usarmy/signal/transport/v1;transportv1"; +option java_package = "mil.army.signal.transport.v1"; + +// Core service for RF link telemetry, topology synchronization, and agentic AI directives +service SignalTransportEngine { + rpc ReportLinkTelemetry (TelemetryRequest) returns (TelemetryResponse); + rpc StreamSpectrumData (stream SpectrumChunk) returns (stream OptimizationRecommendation); + rpc SyncCRDTDelta (CRDTDeltaRequest) returns (CRDTDeltaResponse); +} + +enum NodeRole { + ROLE_UNSPECIFIED = 0; + ROLE_SIGNAL_PLANNER = 1; + ROLE_NETWORK_ENGINEER = 2; + ROLE_MAINTENANCE_OPERATOR = 3; + ROLE_COMMAND_OFFICER = 4; +} + +message GPSCoordinates { + double latitude = 1; + double longitude = 2; + float altitude_m = 3; +} + +message TelemetryRequest { + string node_id = 1; + uint64 timestamp_hlc = 2; // Hybrid Logical Clock timestamp + double frequency_mhz = 3; + float snr_db = 4; + float packet_loss_rate = 5; + int32 tx_power_dbm = 6; + GPSCoordinates position = 7; + NodeRole operator_role = 8; +} + +message TelemetryResponse { + bool acknowledged = 1; + uint32 status_code = 2; + string message = 3; +} + +message SpectrumChunk { + string sensor_node_id = 1; + double start_freq_mhz = 2; + double end_freq_mhz = 3; + uint64 timestamp_utc = 4; + bytes power_spectral_density_dbm = 5; // Compressed float array (zstd) +} + +message OptimizationRecommendation { + string recommendation_id = 1; + string target_node_id = 2; + enum ActionType { + ACTION_UNSPECIFIED = 0; + CHANGE_FREQUENCY = 1; + ADJUST_POWER = 2; + REROUTE_TRAFFIC = 3; + TRIGGER_PMCS_ALERT = 4; + } + ActionType action = 3; + double target_frequency_mhz = 4; + int32 target_power_dbm = 5; + string rationale = 6; + float confidence_score = 7; +} + +message CRDTDeltaRequest { + string source_node_id = 1; + uint64 vector_clock_time = 2; + NodeRole operator_role = 3; + bytes state_delta_payload = 4; // Serialized LWW-Element-Set delta + string payload_signature = 5; // Cryptographic HMAC / Ed25519 signature +} + +message CRDTDeltaResponse { + bool applied_successfully = 1; + uint64 local_vector_clock_time = 2; + string conflict_resolution_note = 3; +} +``` diff --git a/docs/security/03_security_and_defense.md b/docs/security/03_security_and_defense.md new file mode 100644 index 0000000..28a314f --- /dev/null +++ b/docs/security/03_security_and_defense.md @@ -0,0 +1,39 @@ +# Security Architecture & Defensive Modeling Matrix + +## 1. OSI Layer Defensive Framework +The system implements defensive measures across OSI Layers 1 through 7 to maintain operational integrity in contested electronic environments. + +``` +OSI Layer 7 (Application) --> Zero Trust Identity, Cryptographic Token Revocation, ABAC +OSI Layer 6 (Presentation) --> Protobuf Serialization & End-to-End Payload Encryption +OSI Layer 5 (Session) --> Store-and-Forward Session Resiliency & Delay-Tolerant Net +OSI Layer 4 (Transport) --> Mutually Authenticated TLS (mTLS) / Noise Protocol Framework +OSI Layer 3 (Network) --> Dynamic Mesh Routing, Dynamic IPsec & WireGuard Tunnels +OSI Layer 2 (Data Link) --> L2 Anti-Jamming, Frequency Hopping & MAC Security (MACsec) +OSI Layer 1 (Physical) --> COMSEC Hardware (Type-1), Low Probability of Intercept (LPI) +``` + +--- + +## 2. Layer-by-Layer Defensive Mapping + +| OSI Layer | Hardware & Medium Scope | Security / Defensive Implementation | Tactical Failure Mode Mitigations | +| :--- | :--- | :--- | :--- | +| **L1 Physical** | Copper, Fiber (TFOCA-II), RF (SINCGARS, MPU5, TSM, Link 16) | Type-1 NSA COMSEC/EMSEC, LPI/LPD directional beamforming | Hardware Abstraction Layer monitors RSSI/SNR; detects directional RF jamming | +| **L2 Data Link** | Tactical Ethernet, P2P RF | IEEE 802.1AE MACsec, dynamic TDMA slot management | Rogue MAC detection triggers immediate port lockout and operator alert | +| **L3 Network** | IPv4/IPv6 Tactical Mesh (AOR, OLSRv2) | Dynamic IPsec (HAIPE) / WireGuard Mesh tunnels, dynamic IP masking | Anti-traffic-analysis routing obfuscation over contested backhauls | +| **L4 Transport** | TCP, UDP, DTN (RFC 9171) | mTLS 1.3, Noise Protocol Framework | Automatic fallback to UDP/DTN bundle transport when packet loss $> 15\%$ | +| **L5 Session** | Session Resiliency Layer | Cryptographically signed ephemeral tokens | Automatic store-and-forward queue caching during link drops | +| **L6 Presentation** | Protocol Buffers v3 | Payload AEAD Encryption (AES-256-GCM / ChaCha20-Poly1305) | Memory-zeroing buffers after serialization to prevent cold-boot extraction | +| **L7 Application** | Tactical Web, Android App, gRPC APIs | Zero Trust Architecture (ZTA), Attribute-Based Access Control (ABAC) | Real-time token introspection, fine-grained endpoint authorization, anti-replay nonces | + +--- + +## 3. RBAC / ABAC Permission Hierarchy + +| Role | Domain Scope | Permissions | Security Ceiling | +| :--- | :--- | :--- | :--- | +| **Signal Planner** | Enterprise / Battalion Wide | Create/Edit link plans, assign IP blocks, modify RF profiles, issue orders | Enclave Level (Up to Secret/TS) | +| **Network Engineer** | Node / Hardware Level | Push configurations, modify QoS policies, load COMSEC keys, execute RF tuning | Enclave Level | +| **Maintenance Operator** | Equipment / Field Ops | Read link parameters, write PMCS logs, update hardware status, log tickets | Unclassified / Operational Data | +| **Command Officer** | Operational Overlay | Read-only access to readiness dashboards, coverage maps, and link metrics | Enclave Level | diff --git a/docs/workflows/04_workflows_and_crdt.md b/docs/workflows/04_workflows_and_crdt.md new file mode 100644 index 0000000..6e05d1d --- /dev/null +++ b/docs/workflows/04_workflows_and_crdt.md @@ -0,0 +1,49 @@ +# ITSM Workflows & CRDT State Synchronization Engine + +## 1. Signal Operational Lifecycle Workflow + +``` +[ Phase 1: Link Engineering ] + │ + ▼ +[ Phase 2: Installation Sync ] ──► (Automated Cut-Sheet & Config Generation) + │ + ▼ +[ Phase 3: Spectrum Resourcing ] ──► (SJS/SMART Spectrum Allocation Checks) + │ + ▼ +[ Phase 4: Operational Monitoring & ITSM ] ──► (Incident/Problem Tracking & Telemetry) + │ + ▼ +[ Phase 5: Preventive Maintenance ] ──► (PMCS Schedule & Resource Tracking) + │ + ▼ +[ Phase 6: Governance Compliance ] ──► (AAR, Audit Trail & Policy Verification) +``` + +--- + +## 2. Multi-User CRDT Conflict Resolution Engine + +To support offline multi-user synchronization across intermittent RF networks, all system entity state edits are modeled as **Conflict-Free Replicated Data Types (CRDTs)** using an **LWW-Element-Set** (Last-Write-Wins Element Set) driven by Hybrid Logical Clocks (HLC). + +### Deconfliction Sequence & Deterministic Rules + +``` +Node Alpha (Signal Planner): Edits Node-1 Freq -> 420 MHz [Vector Clock: {A:1, B:0}] + │ + (Intermittent RF Mesh Link) + │ +Node Bravo (Network Engineer): Edits Node-1 Freq -> 425 MHz [Vector Clock: {A:0, B:1}] + │ + ▼ + [ CRDT Resolution Engine ] + (LWW-Element-Set + Vector Clock Compare) + │ + Final Deterministic State Applied +``` + +### Deterministic Rule Enforcement +1. **Rule 1 (Role Authority Tiering):** If two conflicting edits occur within the clock skew window ($\le 500\text{ ms}$), the modification originating from the higher RBAC role (e.g., Signal Planner over Network Engineer) supersedes. +2. **Rule 2 (Hybrid Logical Clock Ordering):** If RBAC tiers are equal, the higher HLC timestamp (`Timestamp_UTC + LogicalCounter`) wins. +3. **Rule 3 (Public Key Tie-Breaker):** If HLC timestamps match identically, the lower lexicographical value of the operator's public cryptographic key signature breaks the tie deterministically across all nodes. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..41e4bfa --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,20 @@ +site_name: Signal Transport Planning & Operations Tool +site_description: Technical design documentation for US Army Signal Transport planning software. + +theme: + name: material + palette: + scheme: slate + primary: blue grey + accent: cyan + features: + - navigation.indexes + - navigation.instant + - content.code.copy + +nav: + - Home: index.md + - Architecture: architecture/01_system_architecture.md + - Protocols & APIs: protocols/02_api_and_protocols.md + - Security Architecture: security/03_security_and_defense.md + - Workflows & CRDT: workflows/04_workflows_and_crdt.md