feat: initialize documentation structure and CI workflow
This commit is contained in:
commit
8ed0df3dce
|
|
@ -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"
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
.vscode/
|
||||
site/
|
||||
*.tmp
|
||||
*.log
|
||||
|
|
@ -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)
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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;
|
||||
}
|
||||
```
|
||||
|
|
@ -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 |
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue