commit ee72edacb08ef6850727850eafaf36632780126a Author: UTO Manager Dev Date: Fri Aug 7 09:43:56 2026 -0400 chore: initial project setup — git, README, .gitignore, MkDocs, VSCode diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d9d03d2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,293 @@ +# ============================================================================= +# UTO Manager — Flutter / Dart / VSCode / MkDocs .gitignore +# U.S. Army Unit Task Organization Enterprise System +# ============================================================================= + +# ----------------------------------------------------------------------------- +# Flutter / Dart +# ----------------------------------------------------------------------------- + +# Dart tool cache +.dart_tool/ +.flutter-plugins +.flutter-plugins-dependencies + +# Flutter build outputs +build/ +*.apk +*.aab +*.ipa +*.app +*.exe +*.msix +*.msi + +# Dart generated files +*.g.dart +*.freezed.dart +*.gr.dart +*.mocks.dart + +# Drift / SQLite generated files +*.drift.dart +*.g.dart + +# Protobuf generated files +*.pb.dart +*.pbenum.dart +*.pbgrpc.dart +*.pbjson.dart + +# pubspec lock (keep for reproducible builds — comment out if desired) +# pubspec.lock + +# Flutter web build +web/flutter_service_worker.js +web/flutter.js +web/flutter_bootstrap.js +web/version.json +web/main.dart.js +web/main.dart.js.map + +# Flutter Windows build artifacts +windows/flutter/generated_plugin_registrant.cc +windows/flutter/generated_plugin_registrant.h +windows/flutter/generated_plugins.cmake +windows/flutter/ephemeral/ + +# Flutter Android build artifacts +android/.gradle/ +android/local.properties +android/key.properties +android/app/google-services.json +android/app/debug.keystore +android/app/release.keystore +android/app/upload-keystore.jks +android/captures/ +android/gradlew +android/gradlew.bat +android/gradle/ + +# Flutter iOS (future target) +ios/Flutter/App.framework +ios/Flutter/Flutter.framework +ios/Flutter/Flutter.podspec +ios/Flutter/Generated.xcconfig +ios/Flutter/ephemeral/ +ios/Flutter/app.flx +ios/Flutter/app.zip +ios/Flutter/flutter_assets/ +ios/ServiceDefinitions.json +ios/Runner/GeneratedPluginRegistrant.* +ios/Pods/ +ios/.symlinks/ +ios/Flutter/flutter_export_environment.sh + +# Dart analysis cache +.dart_tool/ +analysis_options.yaml.bak + +# Coverage reports +coverage/ +lcov.info +*.lcov + +# Dart pub cache (local) +.pub-cache/ +.pub/ + +# Flutter DevTools +.devtools + +# ----------------------------------------------------------------------------- +# Visual Studio Code +# ----------------------------------------------------------------------------- + +# VSCode workspace settings (keep .vscode/settings.json if team-shared) +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +!.vscode/*.code-snippets + +# VSCode local history +.history/ +*.vsix + +# VSCode test results +.vscode-test/ + +# ----------------------------------------------------------------------------- +# MkDocs / Python Documentation +# ----------------------------------------------------------------------------- + +# MkDocs build output +site/ + +# Python virtual environments +.venv/ +venv/ +env/ +ENV/ +.env/ + +# Python cache +__pycache__/ +*.py[cod] +*$py.class +*.pyo +*.pyd +.Python + +# Python package build artifacts +dist/ +*.egg-info/ +*.egg +MANIFEST + +# pip +pip-log.txt +pip-delete-this-directory.txt + +# MkDocs cache +.cache/ +.mkdocs_cache/ + +# Jupyter Notebooks (if used for documentation) +.ipynb_checkpoints/ + +# ----------------------------------------------------------------------------- +# Operating System +# ----------------------------------------------------------------------------- + +# Windows +Thumbs.db +Thumbs.db:encryptable +ehthumbs.db +ehthumbs_vista.db +Desktop.ini +$RECYCLE.BIN/ +*.lnk +*.stackdump + +# macOS +.DS_Store +.AppleDouble +.LSOverride +._* +.DocumentRevisions-V100 +.fseventsd +.Spotlight-V100 +.TemporaryItems +.Trashes +.VolumeIcon.icns +.com.apple.timemachine.donotpresent + +# Linux +*~ +.fuse_hidden* +.directory +.Trash-* +.nfs* + +# ----------------------------------------------------------------------------- +# Security & Secrets +# ----------------------------------------------------------------------------- + +# Environment variable files +.env +.env.* +!.env.example +*.env + +# Key files and certificates +*.pem +*.key +*.p12 +*.pfx +*.jks +*.keystore +google-services.json +GoogleService-Info.plist + +# SQLCipher / database encryption keys +*.db-key +*.sqlite-key + +# Firebase +firebase.json +.firebaserc +firebase-debug.log + +# ----------------------------------------------------------------------------- +# CI/CD & Build Tools +# ----------------------------------------------------------------------------- + +# GitHub Actions local runner cache +.act/ + +# Gradle +.gradle/ +gradle-app.setting +!gradle-wrapper.jar +!gradle-wrapper.properties + +# CMake (Windows native build) +CMakeCache.txt +CMakeFiles/ +CMakeScripts/ +cmake_install.cmake +install_manifest.txt +compile_commands.json +CTestTestfile.cmake +_deps/ + +# Ninja build files +*.ninja +*.ninja_deps +*.ninja_log + +# ----------------------------------------------------------------------------- +# Logs & Temporary Files +# ----------------------------------------------------------------------------- + +# Log files +*.log +logs/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Temporary files +*.tmp +*.temp +*.swp +*.swo +*~ +.~lock.* + +# Test output +test-results/ +test_results/ +junit.xml + +# ----------------------------------------------------------------------------- +# Project-Specific +# ----------------------------------------------------------------------------- + +# UTO project save files (user data — not source controlled) +*.uto + +# Exported organizational charts (generated artifacts) +exports/ + +# Local MOS dictionary overrides (use committed version) +local_mos_override.json + +# Performance benchmark raw data +benchmarks/raw/ + +# DevTools snapshots +*.devtools_snapshot +*.heapsnapshot diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..2e34c58 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,5 @@ +{ + "default": true, + "MD013": false, + "MD060": false +} diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..0777e83 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,31 @@ +{ + // Recommended VSCode extensions for UTO Manager Flutter development + "recommendations": [ + // Flutter & Dart + "dart-code.flutter", + "dart-code.dart-code", + + // Documentation (MkDocs) + "davidanson.vscode-markdownlint", + "yzhang.markdown-all-in-one", + "bierner.markdown-mermaid", + "ms-python.python", + "ms-python.vscode-pylance", + + // YAML (mkdocs.yml) + "redhat.vscode-yaml", + + // Git + "eamodio.gitlens", + "mhutchie.git-graph", + + // Code Quality + "usernamehw.errorlens", + "streetsidesoftware.code-spell-checker", + + // Productivity + "gruntfuggly.todo-tree", + "christian-kohler.path-intellisense", + "editorconfig.editorconfig" + ] +} diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..575cf14 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,54 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "UTO Manager (Windows)", + "request": "launch", + "type": "dart", + "flutterMode": "debug", + "deviceId": "windows" + }, + { + "name": "UTO Manager (Chrome)", + "request": "launch", + "type": "dart", + "flutterMode": "debug", + "deviceId": "chrome" + }, + { + "name": "UTO Manager (Chrome — WASM)", + "request": "launch", + "type": "dart", + "flutterMode": "debug", + "deviceId": "chrome", + "args": ["--wasm"] + }, + { + "name": "UTO Manager (Android)", + "request": "launch", + "type": "dart", + "flutterMode": "debug", + "deviceId": "android" + }, + { + "name": "UTO Manager (Windows — Profile)", + "request": "launch", + "type": "dart", + "flutterMode": "profile", + "deviceId": "windows" + }, + { + "name": "UTO Manager (Android — Profile)", + "request": "launch", + "type": "dart", + "flutterMode": "profile", + "deviceId": "android" + }, + { + "name": "Flutter Tests", + "request": "launch", + "type": "dart", + "program": "test/" + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..ec8a0d1 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,129 @@ +{ + // ------------------------------------------------------------------------- + // Flutter / Dart + // ------------------------------------------------------------------------- + "dart.flutterSdkPath": null, + "dart.debugExternalPackageLibraries": false, + "dart.debugSdkLibraries": false, + "dart.lineLength": 100, + "dart.showTodos": true, + "dart.enableSdkFormatter": true, + "[dart]": { + "editor.formatOnSave": true, + "editor.formatOnType": true, + "editor.rulers": [100], + "editor.selectionHighlight": false, + "editor.suggest.snippetsPreventQuickSuggestions": false, + "editor.suggestSelection": "first", + "editor.tabCompletion": "onlySnippets", + "editor.wordBasedSuggestions": "off" + }, + + // ------------------------------------------------------------------------- + // Editor — General + // ------------------------------------------------------------------------- + "editor.fontSize": 14, + "editor.tabSize": 2, + "editor.insertSpaces": true, + "editor.detectIndentation": false, + "editor.formatOnSave": true, + "editor.formatOnPaste": false, + "editor.minimap.enabled": true, + "editor.wordWrap": "off", + "editor.renderWhitespace": "boundary", + "editor.bracketPairColorization.enabled": true, + "editor.guides.bracketPairs": true, + "editor.inlayHints.enabled": "on", + "editor.linkedEditing": true, + + // ------------------------------------------------------------------------- + // Files + // ------------------------------------------------------------------------- + "files.trimTrailingWhitespace": true, + "files.insertFinalNewline": true, + "files.trimFinalNewlines": true, + "files.eol": "\n", + "files.exclude": { + "**/.dart_tool": true, + "**/.flutter-plugins": true, + "**/.flutter-plugins-dependencies": true, + "**/build": true, + "**/.pub-cache": true, + "**/site": true, + "**/__pycache__": true, + "**/.venv": true + }, + "files.watcherExclude": { + "**/.dart_tool/**": true, + "**/build/**": true, + "**/site/**": true, + "**/.venv/**": true + }, + + // ------------------------------------------------------------------------- + // Search + // ------------------------------------------------------------------------- + "search.exclude": { + "**/build": true, + "**/.dart_tool": true, + "**/site": true, + "**/.venv": true, + "**/__pycache__": true + }, + + // ------------------------------------------------------------------------- + // Markdown + // ------------------------------------------------------------------------- + "[markdown]": { + "editor.formatOnSave": false, + "editor.wordWrap": "on", + "editor.quickSuggestions": { + "comments": "off", + "strings": "off", + "other": "off" + } + }, + "markdownlint.config": { + "extends": ".markdownlint.json" + }, + + // ------------------------------------------------------------------------- + // YAML (mkdocs.yml) + // ------------------------------------------------------------------------- + "[yaml]": { + "editor.formatOnSave": true, + "editor.tabSize": 2, + "editor.insertSpaces": true + }, + "yaml.schemas": { + "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml" + }, + "yaml.customTags": [ + "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji mapping", + "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg mapping", + "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format mapping" + ], + + // ------------------------------------------------------------------------- + // Python (MkDocs) + // ------------------------------------------------------------------------- + "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe", + "[python]": { + "editor.formatOnSave": true, + "editor.tabSize": 4 + }, + + // ------------------------------------------------------------------------- + // Git + // ------------------------------------------------------------------------- + "git.enableSmartCommit": true, + "git.confirmSync": false, + "git.autofetch": true, + "git.branchProtection": ["main"], + + // ------------------------------------------------------------------------- + // Terminal + // ------------------------------------------------------------------------- + "terminal.integrated.defaultProfile.windows": "Command Prompt", + "terminal.integrated.fontSize": 13 +} diff --git a/README.md b/README.md new file mode 100644 index 0000000..45ebb3a --- /dev/null +++ b/README.md @@ -0,0 +1,286 @@ +# UTO Manager + +## Flutter-Based Military Unit Task Organization Enterprise System + +### U.S. Army 2026 Doctrine — Cross-Platform Command & Control Application + +--- + +[![Flutter](https://img.shields.io/badge/Flutter-3.x-02569B?logo=flutter)](https://flutter.dev) +[![Dart](https://img.shields.io/badge/Dart-3.x-0175C2?logo=dart)](https://dart.dev) +[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Web%20%7C%20Android-brightgreen)](https://flutter.dev/multi-platform) +[![License](https://img.shields.io/badge/License-Proprietary-red)](LICENSE) +[![Docs](https://img.shields.io/badge/Docs-MkDocs-526CFE?logo=materialformkdocs)](https://www.mkdocs.org) + +--- + +## Overview + +**UTO Manager** is a cross-platform command and control (C2) application for creating, visualizing, and validating U.S. Army unit task organizations (UTOs) in accordance with 2026 Army doctrine. Built with Flutter, the application targets **Windows x64**, **Web (WASM/CanvasKit)**, and **Android** from a single Dart codebase. + +The system models military formations from individual soldier positions up to multi-domain Brigade Combat Teams, enforcing Modified Table of Organization and Equipment (MTOE) doctrinal rules in real time. + +--- + +## Key Features + +- **Interactive Visual Canvas** — GPU-accelerated `CustomPainter` engine with pan/zoom, viewport culling, and 60 FPS rendering at 5,000+ nodes +- **Drag-and-Drop Re-parenting** — Cross-platform state machine with doctrinal validation highlights (green/red) and undo/redo support +- **MIL-STD-2525D Symbology** — Hybrid rendering pipeline: `milsymbol.js` on Web, native SVG path engine on Windows/Android +- **2026 Doctrinal Templates** — Pre-configured JSON templates for MBCT, SBCT, ABCT, CAB-Heavy, and CAB-Light formations +- **Real-Time MTOE Validation** — Background Dart Isolate engine detecting MOS mismatches, rank violations, vacant leadership slots, and structural hierarchy errors +- **Offline-First Architecture** — Drift/SQLite persistence with delta synchronization for contested network environments +- **Multi-Format Export** — JSON, Protobuf, and vector PDF organizational chart export + +--- + +## Platform Targets + +| Platform | Deployment | Performance Target | +|---|---|---| +| Windows x64 | Native `.msi` / `.exe` | 60 FPS @ 5,000+ nodes | +| Web (WASM) | WebAssembly + CanvasKit | 60 FPS @ 2,000+ nodes | +| Android | Native `.apk` / `.aab` | 60 FPS @ 1,500+ nodes | + +--- + +## Architecture + +```text +[Presentation Layer: CustomPainter / InteractiveViewer / Responsive Shell] + │ + ▼ +[Application State Layer: BLoC / Signals / Super Drag-and-Drop Pipeline] + │ + ▼ +[Domain Layer: MTOE Doctrinal Rules Engine / Structural Validation] + │ + ▼ +[Infrastructure Layer: Drift SQLite / IndexedDB / Protobuf Codecs] +``` + +### Project Structure + +```text +lib/ +├── domain/ # Entities, value objects, repository interfaces +│ ├── entities/ # UnitNode, PositionSlot, PersonnelRecord +│ ├── enums/ # Echelon, DoctrinalBranch, AuthorizedRank +│ └── repositories/ # Abstract repository contracts +├── application/ # BLoC / use cases / state management +│ ├── blocs/ # State management BLoCs +│ └── use_cases/ # Domain use case implementations +├── infrastructure/ # Drift DB, IndexedDB adapters, Protobuf codecs +│ ├── database/ # Drift table definitions and DAOs +│ ├── codecs/ # JSON and Protobuf serialization +│ └── sync/ # Delta synchronization engine +└── presentation/ # Widgets, painters, responsive shell + ├── canvas/ # CustomPainter, InteractiveViewer, viewport + ├── layout/ # Reingold-Tilford algorithm, Quadtree index + ├── symbology/ # MIL-STD-2525D rendering pipeline + └── shell/ # Three-pane UI, responsive layouts +``` + +--- + +## Getting Started + +### Prerequisites + +- [Flutter SDK](https://docs.flutter.dev/get-started/install) 3.x or later +- [Dart SDK](https://dart.dev/get-dart) 3.x (included with Flutter) +- [Visual Studio 2022](https://visualstudio.microsoft.com/) with **Desktop development with C++** workload (Windows target) +- [Android Studio](https://developer.android.com/studio) with Android SDK (Android target) +- [Python 3.9+](https://www.python.org/) with `pip` (MkDocs documentation) +- [Git](https://git-scm.com/) + +### Clone the Repository + +```bash +git clone https://git.kellsupport.com/uto_manager.git +cd uto_manager +``` + +### Install Flutter Dependencies + +```bash +flutter pub get +``` + +### Run the Application + +```bash +# Windows desktop +flutter run -d windows + +# Web (Chrome) +flutter run -d chrome + +# Web (WASM mode) +flutter run -d chrome --wasm + +# Android (connected device or emulator) +flutter run -d android +``` + +### Run Tests + +```bash +# All tests +flutter test + +# With coverage +flutter test --coverage + +# Static analysis +flutter analyze +``` + +### Build Release Packages + +```bash +# Windows +flutter build windows --release + +# Web (WASM) +flutter build web --wasm --release + +# Android APK +flutter build apk --release + +# Android App Bundle (Google Play) +flutter build appbundle --release +``` + +--- + +## Documentation + +Project documentation is built with [MkDocs](https://www.mkdocs.org/) using the [Material theme](https://squidfunk.github.io/mkdocs-material/). + +### Install Documentation Dependencies + +```bash +pip install -r docs/requirements.txt +``` + +### Serve Documentation Locally + +```bash +mkdocs serve +``` + +Then open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser. + +### Build Documentation Site + +```bash +mkdocs build +``` + +Output is written to the `site/` directory (excluded from version control). + +--- + +## Development Workflow + +### Branch Strategy + +| Branch | Purpose | +|---|---| +| `main` | Production-ready releases only | +| `develop` | Integration branch for completed features | +| `feature/*` | Individual feature development | +| `fix/*` | Bug fixes | +| `release/*` | Release preparation and stabilization | + +### Commit Convention + +This project follows [Conventional Commits](https://www.conventionalcommits.org/): + +```text +feat(canvas): implement viewport culling via inverse matrix transform +fix(validation): correct MOS mismatch detection for 68W slots +docs(readme): update platform prerequisites +chore(deps): upgrade drift to 2.x +``` + +### Code Quality + +```bash +# Format code +dart format . + +# Analyze code +flutter analyze + +# Run linter +dart run dart_code_metrics:metrics analyze lib +``` + +--- + +## Technology Stack + +| Layer | Technology | Purpose | +|---|---|---| +| UI Framework | Flutter (Dart) | Single codebase for Windows, Web, Android | +| Rendering | CustomPainter + InteractiveViewer | GPU-direct drawing; bypasses widget tree overhead | +| State Management | BLoC + Signals | Reactive atomic state | +| Drag-and-Drop | super_drag_and_drop | Cross-platform payload integrity | +| Local Database | Drift (SQLite / IndexedDB) | Type-safe reactive ORM; offline-first | +| Encryption | SQLCipher | Data-at-rest protection | +| Symbology (Web) | milsymbol.js via dart:js_interop | Full MIL-STD-2525D compliance | +| Symbology (Native) | path_drawing + SVG assets + LRU cache | Zero external runtime dependencies | +| Background Compute | Dart Isolates | Offload layout, validation, export | +| Serialization | JSON + Protobuf | Human-readable + compact binary export | +| PDF Export | pdf package | Vector-quality organizational chart output | +| Documentation | MkDocs + Material theme | User and developer documentation | + +--- + +## Development Phases + +| Phase | Title | Weeks | Status | +|---|---|---|---| +| Phase 1 | Architecture & Data Foundations | 1 – 4 | ⬜ Not Started | +| Phase 2 | Canvas Graphics Engine & Gesture Subsystem | 5 – 9 | ⬜ Not Started | +| Phase 3 | 2026 Doctrinal Templates & Symbology Engine | 10 – 14 | ⬜ Not Started | +| Phase 4 | Persistence, Validation Rules, & Export Engine | 15 – 19 | ⬜ Not Started | +| Phase 5 | Platform Optimization, Profiling, & Hardening | 20 – 24 | ⬜ Not Started | + +See [`development_status.md`](development_status.md) for detailed task tracking and [`phased_development_plan.md`](phased_development_plan.md) for full phase specifications. + +--- + +## Contributing + +1. Fork the repository and create a `feature/*` branch from `develop` +2. Implement your changes with appropriate unit tests +3. Ensure `flutter analyze` passes with zero violations +4. Ensure `flutter test --coverage` meets the 80% minimum threshold +5. Submit a pull request targeting the `develop` branch +6. Pull requests require passing CI on all three platform targets before merge + +--- + +## Security + +This application is designed for use with U.S. Army organizational data. All local data is encrypted at rest using SQLCipher. Encryption keys are stored in platform keychains (Windows Credential Manager / Android Keystore). + +**Do not commit sensitive data, encryption keys, or classified information to this repository.** + +--- + +## License + +Proprietary — All rights reserved. See [LICENSE](LICENSE) for details. + +--- + +## Related Documents + +- [`master_development_plan.md`](master_development_plan.md) — Full architectural specification +- [`phased_development_plan.md`](phased_development_plan.md) — Phase-by-phase implementation plan +- [`development_status.md`](development_status.md) — Sprint tracking and task status +- [Documentation Site](http://127.0.0.1:8000) — MkDocs user and developer documentation diff --git a/development_status.md b/development_status.md new file mode 100644 index 0000000..fbbd5b4 --- /dev/null +++ b/development_status.md @@ -0,0 +1,648 @@ +# Development Status + +## Flutter-Based Military Unit Task Organization (UTO) Manager + +### U.S. Army 2026 Doctrine — Cross-Platform Enterprise System + +--- + +> **How to use this document:** Update task statuses as work progresses. Use the status legend below. Record blockers, notes, and completion dates in the Notes column. This document is the single source of truth for sprint tracking and stakeholder reporting. + +--- + +## Status Legend + +| Symbol | Status | Meaning | +|---|---|---| +| ⬜ | `NOT STARTED` | Work has not begun | +| 🔵 | `IN PROGRESS` | Actively being worked on | +| ✅ | `COMPLETE` | Done and acceptance criteria verified | +| ⚠️ | `BLOCKED` | Cannot proceed; blocker documented in Notes | +| 🔁 | `IN REVIEW` | Implementation complete; pending review/testing | +| ⏭️ | `DEFERRED` | Intentionally postponed to a later phase | + +--- + +## Overall Project Progress + +| Phase | Title | Weeks | Status | % Complete | +|---|---|---|---|---| +| Phase 1 | Architecture & Data Foundations | 1 – 4 | ⬜ NOT STARTED | 0% | +| Phase 2 | Canvas Graphics Engine & Gesture Subsystem | 5 – 9 | ⬜ NOT STARTED | 0% | +| Phase 3 | 2026 Doctrinal Templates & Symbology Engine | 10 – 14 | ⬜ NOT STARTED | 0% | +| Phase 4 | Persistence, Validation Rules, & Export Engine | 15 – 19 | ⬜ NOT STARTED | 0% | +| Phase 5 | Platform Optimization, Profiling, & Hardening | 20 – 24 | ⬜ NOT STARTED | 0% | + +Overall Project Completion: **0%** + +Current Active Phase: — + +Project Start Date: ___________ + +Target Completion Date: ___________ + +--- + +## Phase 1: Architecture & Data Foundations + +### Weeks 1 – 4 | Status: ⬜ NOT STARTED + +--- + +### 1.1 — Project Scaffolding & Clean Architecture Setup + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 1.1.1 | Initialize Flutter project with `windows`, `web`, `android` targets | ⬜ | | | | | +| 1.1.2 | Establish clean architecture folder structure (`domain/`, `application/`, `infrastructure/`, `presentation/`) | ⬜ | | | | | +| 1.1.3 | Configure `flutter_lints` and `very_good_analysis` lint rules | ⬜ | | | | | +| 1.1.4 | Set up `pubspec.yaml` with initial dependency declarations | ⬜ | | | | | +| 1.1.5 | Initialize Git repository with branch protection rules (`main`, `develop`, `feature/*`) | ⬜ | | | | | + +**1.1 Acceptance Criteria:** + +- [ ] `flutter run -d windows` launches blank scaffold without errors +- [ ] `flutter run -d chrome` launches blank scaffold without errors +- [ ] `flutter run -d android` launches blank scaffold without errors +- [ ] `flutter analyze` passes with zero lint violations + +--- + +### 1.2 — Core Domain Entity Definitions + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 1.2.1 | Define `Echelon` enum (Brigade → Team) | ⬜ | | | | | +| 1.2.2 | Define `DoctrinalBranch` enum (Infantry, Medical, Fires, Signal, CyberEW, Aviation, Logistics, Engineer) | ⬜ | | | | | +| 1.2.3 | Define `AuthorizedRank` enum (E1–E9, W1–W5, O1–O10) | ⬜ | | | | | +| 1.2.4 | Define `UnitNode` entity with all required fields | ⬜ | | | | | +| 1.2.5 | Define `PositionSlot` entity with all required fields | ⬜ | | | | | +| 1.2.6 | Define `PersonnelRecord` entity with all required fields | ⬜ | | | | | +| 1.2.7 | Define `DutyMOS` value object with MOS code validation | ⬜ | | | | | +| 1.2.8 | Build Infantry & Maneuver position slot dictionary (11A, 11B, 15W) | ⬜ | | | | | +| 1.2.9 | Build Medical position slot dictionary (68W) | ⬜ | | | | | +| 1.2.10 | Build Field Artillery position slot dictionary (13F, 13D) | ⬜ | | | | | +| 1.2.11 | Build Signal position slot dictionary (25H, 25B) | ⬜ | | | | | +| 1.2.12 | Build Cyber/EW position slot dictionary (17E) | ⬜ | | | | | +| 1.2.13 | Build Logistics position slot dictionary (92Y, 92A, 91B, 91A) | ⬜ | | | | | +| 1.2.14 | Build Engineer position slot dictionary (12B) | ⬜ | | | | | +| 1.2.15 | Implement `UnitRepository` abstract interface | ⬜ | | | | | +| 1.2.16 | Implement `PersonnelRepository` abstract interface | ⬜ | | | | | +| 1.2.17 | Write unit tests for all domain entity validation logic | ⬜ | | | | | +| 1.2.18 | Create MOS dictionary JSON data file | ⬜ | | | | | + +**1.2 Acceptance Criteria:** + +- [ ] 100% unit test coverage on all domain entity validation logic +- [ ] MOS validation rejects invalid codes +- [ ] MOS validation accepts all defined specialties across all branches + +--- + +### 1.3 — Database Schema & Infrastructure Layer + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 1.3.1 | Add `drift` package; configure for Windows/Android (SQLite) | ⬜ | | | | | +| 1.3.2 | Configure `drift_web` for Web (IndexedDB) | ⬜ | | | | | +| 1.3.3 | Define `units` Drift table schema | ⬜ | | | | | +| 1.3.4 | Define `position_slots` Drift table schema | ⬜ | | | | | +| 1.3.5 | Define `personnel` Drift table schema | ⬜ | | | | | +| 1.3.6 | Define `templates` Drift table schema | ⬜ | | | | | +| 1.3.7 | Implement DAOs for all four tables (CRUD operations) | ⬜ | | | | | +| 1.3.8 | Configure database migrations framework (versioned migration files) | ⬜ | | | | | +| 1.3.9 | Implement `JsonTemplateCodec` for unit tree serialization/deserialization | ⬜ | | | | | +| 1.3.10 | Stub Protobuf schema definitions (`.proto` files) | ⬜ | | | | | +| 1.3.11 | Write integration tests for all DAO operations | ⬜ | | | | | + +**1.3 Acceptance Criteria:** + +- [ ] Integration tests pass: CRUD on all four tables +- [ ] Database migrations run cleanly from version 1 → current +- [ ] JSON round-trip serialization produces identical domain objects + +--- + +### 1.4 — CI/CD Pipeline Configuration + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 1.4.1 | Configure CI pipeline with `flutter build windows` target | ⬜ | | | | | +| 1.4.2 | Configure CI pipeline with `flutter build web --wasm` target | ⬜ | | | | | +| 1.4.3 | Configure CI pipeline with `flutter build apk` target | ⬜ | | | | | +| 1.4.4 | Add `flutter test` and `flutter analyze` automated stages | ⬜ | | | | | +| 1.4.5 | Configure build artifact upload (`.exe`, `web/`, `.apk`) | ⬜ | | | | | +| 1.4.6 | Set up code coverage reporting (80% minimum threshold gate) | ⬜ | | | | | + +**1.4 Acceptance Criteria:** + +- [ ] All three platform builds succeed in CI without manual intervention +- [ ] Pull requests blocked on failing tests or lint violations + +--- + +### Phase 1 Exit Criteria + +| Criterion | Status | Verified By | Date | +|---|---|---|---| +| Clean architecture folder structure established and enforced by linting | ⬜ | | | +| All domain entities defined with full unit test coverage | ⬜ | | | +| Drift database operational on Windows, Web, and Android | ⬜ | | | +| CI/CD pipeline passing on all three platform targets | ⬜ | | | +| MOS dictionary data file complete for all functional branches | ⬜ | | | + +--- + +## Phase 2: Canvas Graphics Engine & Gesture Subsystem + +### Weeks 5 – 9 | Status: ⬜ NOT STARTED + +> **Dependency:** Phase 1 must be complete before Phase 2 begins. + +--- + +### 2.1 — CustomPainter Canvas Engine Foundation + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 2.1.1 | Implement `UtoCanvasPainter extends CustomPainter` with `paint()` rendering loop | ⬜ | | | | | +| 2.1.2 | Implement `shouldRepaint()` with dirty-flag comparison | ⬜ | | | | | +| 2.1.3 | Implement node rendering (`drawRect`, `drawPath`, `drawParagraph`) | ⬜ | | | | | +| 2.1.4 | Implement parent-child connection line rendering | ⬜ | | | | | +| 2.1.5 | Wrap painter in `InteractiveViewer` with `TransformationController` | ⬜ | | | | | +| 2.1.6 | Implement viewport culling via inverse matrix transform (`M⁻¹ × S`) | ⬜ | | | | | +| 2.1.7 | Define `NodeRenderModel` flat list data structure | ⬜ | | | | | +| 2.1.8 | Benchmark: verify 60 FPS at 500 placeholder nodes on all three platforms | ⬜ | | | | | + +**2.1 Acceptance Criteria:** + +- [ ] 60 FPS maintained with 500 placeholder nodes on Windows +- [ ] 60 FPS maintained with 500 placeholder nodes on Web +- [ ] 60 FPS maintained with 500 placeholder nodes on Android +- [ ] Viewport culling demonstrably skips off-screen nodes (verified via paint call counters) + +--- + +### 2.2 — Reingold-Tilford Tree Layout Algorithm + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 2.2.1 | Implement Reingold-Tilford algorithm in dedicated `layout/` module | ⬜ | | | | | +| 2.2.2 | Implement bottom-up subtree width calculation | ⬜ | | | | | +| 2.2.3 | Implement `(x, y)` coordinate assignment per echelon level | ⬜ | | | | | +| 2.2.4 | Enforce horizontal branch separation (Maneuver, Fires, Recon, Engineer, Sustainment) | ⬜ | | | | | +| 2.2.5 | Enforce vertical echelon alignment (Brigade → Individual) | ⬜ | | | | | +| 2.2.6 | Offload layout computation to background Dart Isolate | ⬜ | | | | | +| 2.2.7 | Implement `LayoutResult` message passing (Isolate → main thread) | ⬜ | | | | | +| 2.2.8 | Trigger layout recalculation on: node add, remove, re-parent, template load | ⬜ | | | | | + +**2.2 Acceptance Criteria:** + +- [ ] Layout correctly positions a full BCT (500+ nodes) without visual overlap +- [ ] Layout computation completes in < 100ms for a full BCT on Windows +- [ ] UI thread remains unblocked during layout recalculation (verified via DevTools) + +--- + +### 2.3 — Quadtree Spatial Index + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 2.3.1 | Implement `Quadtree` in pure Dart | ⬜ | | | | | +| 2.3.2 | Implement node bounding box insert on layout completion | ⬜ | | | | | +| 2.3.3 | Implement nearest-neighbor proximity query | ⬜ | | | | | +| 2.3.4 | Implement index update on node position change (drag) | ⬜ | | | | | +| 2.3.5 | Implement entry removal on node deletion | ⬜ | | | | | +| 2.3.6 | Integrate Quadtree with canvas hit-testing pipeline | ⬜ | | | | | +| 2.3.7 | Implement screen-space → canvas-space coordinate transform via `M⁻¹` | ⬜ | | | | | +| 2.3.8 | Write unit tests covering edge cases (overlapping bounds, boundary nodes) | ⬜ | | | | | + +**2.3 Acceptance Criteria:** + +- [ ] Hit-testing correctly identifies nodes in a 1,000-node tree with < 1ms query time +- [ ] No false positives or missed hits in unit tests + +--- + +### 2.4 — Cross-Platform Drag-and-Drop State Machine + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 2.4.1 | Implement `Idle` state: canvas responds to pan/zoom only | ⬜ | | | | | +| 2.4.2 | Implement `DragInitiated` state: node selected, subtree isolated to overlay | ⬜ | | | | | +| 2.4.3 | Implement `DragInProgress` state: Quadtree proximity queries + validation highlights | ⬜ | | | | | +| 2.4.4 | Implement `DropExecuted` state: re-parenting command, DB update, layout recalc | ⬜ | | | | | +| 2.4.5 | Implement desktop gesture threshold: drag after 2-pixel mouse movement | ⬜ | | | | | +| 2.4.6 | Implement mobile gesture threshold: 200ms long-press + haptic feedback | ⬜ | | | | | +| 2.4.7 | Integrate `super_drag_and_drop` package for cross-component payload integrity | ⬜ | | | | | +| 2.4.8 | Implement `DragOverlayPainter` as isolated `RepaintBoundary` layer | ⬜ | | | | | +| 2.4.9 | Implement `AttachNodeCommand` as undoable command object | ⬜ | | | | | +| 2.4.10 | Implement `DetachNodeCommand` as undoable command object | ⬜ | | | | | +| 2.4.11 | Implement undo/redo stack for node re-parenting operations | ⬜ | | | | | +| 2.4.12 | Implement green highlight for valid drop targets | ⬜ | | | | | +| 2.4.13 | Implement red indicator for invalid drop targets | ⬜ | | | | | + +**2.4 Acceptance Criteria:** + +- [ ] Dragging Rifle Squad to Infantry Platoon shows green highlight and completes re-parenting +- [ ] Dragging Fire Team to Brigade HQ shows red invalid indicator +- [ ] 200ms long-press threshold prevents accidental drags on touch devices +- [ ] Undo (Ctrl+Z / gesture) correctly reverses re-parenting operations +- [ ] Drag overlay does not trigger full canvas repaint (verified via DevTools) + +--- + +### Phase 2 Exit Criteria + +| Criterion | Status | Verified By | Date | +|---|---|---|---| +| CustomPainter canvas engine rendering nodes and connection lines with viewport culling | ⬜ | | | +| Reingold-Tilford layout algorithm operational in background Dart Isolate | ⬜ | | | +| Quadtree spatial index integrated with hit-testing pipeline | ⬜ | | | +| Cross-platform drag-and-drop state machine functional on Windows and Android | ⬜ | | | +| 60 FPS maintained at target node counts on all three platforms | ⬜ | | | + +--- + +## Phase 3: 2026 Doctrinal Templates & Symbology Engine + +### Weeks 10 – 14 | Status: ⬜ NOT STARTED + +> **Dependency:** Phase 2 must be complete before Phase 3 begins. + +--- + +### 3.1 — Doctrinal Template Library + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 3.1.1 | Implement JSON-driven runtime template loader | ⬜ | | | | | +| 3.1.2 | Build MBCT JSON template (full brigade structure) | ⬜ | | | | | +| 3.1.3 | Build SBCT JSON template (full brigade structure) | ⬜ | | | | | +| 3.1.4 | Build ABCT JSON template (full brigade structure) | ⬜ | | | | | +| 3.1.5 | Build CAB-Heavy JSON template | ⬜ | | | | | +| 3.1.6 | Build CAB-Light JSON template | ⬜ | | | | | +| 3.1.7 | Implement `TemplateInstantiator` service (JSON → `UnitNode` tree → Drift DB) | ⬜ | | | | | +| 3.1.8 | Implement runtime template reload mechanism (no binary recompilation required) | ⬜ | | | | | +| 3.1.9 | Write integration tests for `TemplateInstantiator` | ⬜ | | | | | + +**3.1 Acceptance Criteria:** + +- [ ] MBCT template instantiation creates correct unit/slot/personnel counts in DB +- [ ] SBCT template instantiation creates correct unit/slot/personnel counts in DB +- [ ] ABCT template instantiation creates correct unit/slot/personnel counts in DB +- [ ] CAB-Heavy template instantiation creates correct unit/slot/personnel counts in DB +- [ ] CAB-Light template instantiation creates correct unit/slot/personnel counts in DB +- [ ] Template instantiation completes in < 2 seconds for a full BCT +- [ ] Updated JSON template files reload correctly without app restart + +--- + +### 3.2 — MIL-STD-2525D Symbology Engine + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 3.2.1 | Integrate `milsymbol.js` via `dart:js_interop` for Web target | ⬜ | | | | | +| 3.2.2 | Implement SIDC → milsymbol.js → SVG path pipeline for Web | ⬜ | | | | | +| 3.2.3 | Bundle SVG assets: affiliation frames (Friendly, Hostile, Neutral, Unknown) | ⬜ | | | | | +| 3.2.4 | Bundle SVG assets: function icons (infantry, medical, signal, artillery, engineer, aviation, EW, UAV, logistics) | ⬜ | | | | | +| 3.2.5 | Bundle SVG assets: echelon modifiers (Team through Division) | ⬜ | | | | | +| 3.2.6 | Implement SVG path parsing via `path_drawing` into immutable `Path` objects at app launch | ⬜ | | | | | +| 3.2.7 | Implement thread-safe LRU cache for parsed `Path` objects (indexed by SIDC) | ⬜ | | | | | +| 3.2.8 | Implement `SidcResolver` mapping `(DoctrinalBranch, Echelon, Affiliation)` → 15-digit SIDC | ⬜ | | | | | +| 3.2.9 | Implement `TacticalSymbolPainter`: Frame + Icon + Echelon Modifier + Text Designator | ⬜ | | | | | +| 3.2.10 | Integrate `TacticalSymbolPainter` into main `UtoCanvasPainter` node rendering loop | ⬜ | | | | | + +**3.2 Acceptance Criteria:** + +- [ ] All defined branch/echelon combinations render correct MIL-STD-2525D symbols +- [ ] Symbol cache hit rate > 95% during normal canvas rendering +- [ ] Symbol rendering adds < 2ms overhead per frame on Android +- [ ] Web target renders symbols via milsymbol.js without visible quality difference from native + +--- + +### 3.3 — Three-Pane UI Shell + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 3.3.1 | Implement application header (Echelon Selector, Doctrinal Mode, Export Tools) | ⬜ | | | | | +| 3.3.2 | Implement left panel: collapsible template palette sidebar | ⬜ | | | | | +| 3.3.3 | Implement left panel: template drag sources (MBCT, SBCT, ABCT, CAB, echelon blocks, duty slots) | ⬜ | | | | | +| 3.3.4 | Implement central canvas workspace integration (canvas + InteractiveViewer) | ⬜ | | | | | +| 3.3.5 | Implement right panel: context-sensitive node inspector | ⬜ | | | | | +| 3.3.6 | Implement right panel: unit ID, MOS, personnel search, weapon assignment, readiness status | ⬜ | | | | | +| 3.3.7 | Implement status bar (scale factor, active node count, MTOE validation status) | ⬜ | | | | | +| 3.3.8 | Implement keyboard shortcuts: `Ctrl+Z`, `Ctrl+Y`, `Ctrl+F`, `Ctrl+D`, `Ctrl+S` | ⬜ | | | | | +| 3.3.9 | Implement mouse-wheel pan/zoom | ⬜ | | | | | +| 3.3.10 | Implement multi-node box selection | ⬜ | | | | | +| 3.3.11 | Implement right-click context menus (desktop) | ⬜ | | | | | +| 3.3.12 | Implement Android navigation drawer (replaces left panel) | ⬜ | | | | | +| 3.3.13 | Implement Android bottom sheet inspector (replaces right panel) | ⬜ | | | | | +| 3.3.14 | Implement tap-and-hold radial menus (Android, replaces right-click) | ⬜ | | | | | +| 3.3.15 | Verify all touch targets ≥ 48×48 dp on Android | ⬜ | | | | | + +**3.3 Acceptance Criteria:** + +- [ ] Three-pane layout renders correctly at 1920×1080 on Windows +- [ ] Three-pane layout renders correctly at 2560×1440 on Windows +- [ ] Mobile layout correctly switches to drawer/bottom-sheet on Android +- [ ] All keyboard shortcuts function correctly on Windows and Web +- [ ] Touch targets meet 48×48 dp minimum on Android + +--- + +### Phase 3 Exit Criteria + +| Criterion | Status | Verified By | Date | +|---|---|---|---| +| All five BCT doctrinal templates instantiable from JSON | ⬜ | | | +| MIL-STD-2525D symbology rendering on all three platforms | ⬜ | | | +| Three-pane UI shell functional on desktop and adaptive on Android | ⬜ | | | +| Runtime template reload mechanism operational | ⬜ | | | + +--- + +## Phase 4: Persistence, Validation Rules, & Export Engine + +### Weeks 15 – 19 | Status: ⬜ NOT STARTED + +> **Dependency:** Phase 3 must be complete before Phase 4 begins. + +--- + +### 4.1 — Full Persistence Integration & Offline-First Architecture + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 4.1.1 | Complete Drift repository implementations for all four tables | ⬜ | | | | | +| 4.1.2 | Implement reactive Drift `watchAll()` streams feeding BLoC state | ⬜ | | | | | +| 4.1.3 | Implement `CommandEventStore` with local offline queue | ⬜ | | | | | +| 4.1.4 | Implement `AttachNodeEvent` command event type | ⬜ | | | | | +| 4.1.5 | Implement `DetachNodeEvent` command event type | ⬜ | | | | | +| 4.1.6 | Implement `AssignPersonnelEvent` command event type | ⬜ | | | | | +| 4.1.7 | Implement `UnassignPersonnelEvent` command event type | ⬜ | | | | | +| 4.1.8 | Implement `ModifySlotEvent` command event type | ⬜ | | | | | +| 4.1.9 | Implement `DeltaSynchronizer` (transmit queued events on reconnection) | ⬜ | | | | | +| 4.1.10 | Implement conflict resolution strategy (last-write-wins + conflict flagging) | ⬜ | | | | | +| 4.1.11 | Configure `drift_web` for IndexedDB persistence on Web target | ⬜ | | | | | +| 4.1.12 | Implement database backup/restore (export to encrypted JSON archive) | ⬜ | | | | | + +**4.1 Acceptance Criteria:** + +- [ ] Application continues full operation with zero network connectivity +- [ ] Delta synchronizer transmits only changed events (not full model) on reconnection +- [ ] Reactive streams update UI within 16ms of database write +- [ ] Backup/restore round-trip produces identical database state + +--- + +### 4.2 — Real-Time MTOE Domain Validation Engine + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 4.2.1 | Implement `MtoeValidationEngine` in background Dart Isolate | ⬜ | | | | | +| 4.2.2 | Implement MOS Mismatch Detection rule | ⬜ | | | | | +| 4.2.3 | Implement Rank Mismatch Detection rule | ⬜ | | | | | +| 4.2.4 | Implement Vacant Leadership Slot Detection rule | ⬜ | | | | | +| 4.2.5 | Implement Missing Critical Support Role Detection rule (68W, 13F) | ⬜ | | | | | +| 4.2.6 | Implement Structural Hierarchy Violation Detection rule | ⬜ | | | | | +| 4.2.7 | Implement Doctrinal Strength Deviation rule (< 70% manning) | ⬜ | | | | | +| 4.2.8 | Implement `ValidationFinding` result model (severity, unitId, slotId, findingCode, description) | ⬜ | | | | | +| 4.2.9 | Integrate validation findings into status bar (aggregate counts by severity) | ⬜ | | | | | +| 4.2.10 | Integrate validation findings into node visual indicators (colored border/badge) | ⬜ | | | | | +| 4.2.11 | Integrate validation findings into right panel inspector (detailed finding list) | ⬜ | | | | | +| 4.2.12 | Implement drag-and-drop pre-validation (evaluate before drop execution) | ⬜ | | | | | + +**4.2 Acceptance Criteria:** + +- [ ] All six validation rules correctly identify violations in test unit trees +- [ ] Validation engine processes a full BCT (500+ nodes) in < 500ms in background Isolate +- [ ] Node visual indicators update within one frame of validation completion +- [ ] Dragging Fire Team to Brigade HQ shows red pre-validation indicator before drop + +--- + +### 4.3 — Data Export Engine + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 4.3.1 | Implement JSON export module (full unit tree serialization) | ⬜ | | | | | +| 4.3.2 | Implement Protobuf export module (binary-encoded unit tree) | ⬜ | | | | | +| 4.3.3 | Implement vector PDF export: org chart rendering via `pdf` package | ⬜ | | | | | +| 4.3.4 | Implement PDF export: MIL-STD-2525D symbols as vector paths | ⬜ | | | | | +| 4.3.5 | Implement PDF export: configurable page sizes (Letter, A4, Tabloid/A3) | ⬜ | | | | | +| 4.3.6 | Implement PDF export: cover page with unit designation, date, classification placeholder | ⬜ | | | | | +| 4.3.7 | Implement JSON import pipeline with doctrinal validation | ⬜ | | | | | +| 4.3.8 | Implement export UI dialog (format selection, scope selection, file save) | ⬜ | | | | | +| 4.3.9 | Offload JSON/Protobuf serialization to background Dart Isolate | ⬜ | | | | | +| 4.3.10 | Offload PDF rendering to background Dart Isolate | ⬜ | | | | | + +**4.3 Acceptance Criteria:** + +- [ ] JSON export/import round-trip produces identical unit tree +- [ ] Protobuf export file size < 50% of equivalent JSON for a full BCT +- [ ] PDF export renders all MIL-STD-2525D symbols as vector paths (not rasterized) +- [ ] PDF export completes in < 10 seconds for a full BCT on Windows + +--- + +### Phase 4 Exit Criteria + +| Criterion | Status | Verified By | Date | +|---|---|---|---| +| Full reactive Drift persistence layer operational on all three platforms | ⬜ | | | +| Offline-first operation verified with delta synchronization | ⬜ | | | +| MTOE validation engine detecting all defined violation types in real time | ⬜ | | | +| JSON, Protobuf, and vector PDF export modules functional | ⬜ | | | +| JSON import pipeline with doctrinal validation | ⬜ | | | + +--- + +## Phase 5: Platform Optimization, Profiling, & Hardening + +### Weeks 20 – 24 | Status: ⬜ NOT STARTED + +> **Dependency:** Phase 4 must be complete before Phase 5 begins. + +--- + +### 5.1 — Performance Profiling & Rendering Optimization + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 5.1.1 | Profile Windows target: frame timeline, memory, CPU via Flutter DevTools | ⬜ | | | | | +| 5.1.2 | Profile Web (WASM) target: frame timeline, memory, CPU via Flutter DevTools | ⬜ | | | | | +| 5.1.3 | Profile Android target: frame timeline, memory, CPU via Flutter DevTools | ⬜ | | | | | +| 5.1.4 | Apply `RepaintBoundary` isolation: static layer (grid, connection lines) | ⬜ | | | | | +| 5.1.5 | Apply `RepaintBoundary` isolation: dynamic layer (drag preview overlay) | ⬜ | | | | | +| 5.1.6 | Apply `RepaintBoundary` isolation: node layer (individual unit nodes) | ⬜ | | | | | +| 5.1.7 | Optimize Reingold-Tilford: cache subtree widths, skip unchanged subtrees | ⬜ | | | | | +| 5.1.8 | Optimize Quadtree: bulk-insert for template instantiation, lazy rebuild | ⬜ | | | | | +| 5.1.9 | Tune LRU symbol cache capacity per platform (Windows: 2,000 / Android: 500 / Web: 1,000) | ⬜ | | | | | +| 5.1.10 | Implement progressive loading for large templates (visible viewport first) | ⬜ | | | | | +| 5.1.11 | Build automated performance benchmark suite (frame rate tests at target node counts) | ⬜ | | | | | + +**5.1 Acceptance Criteria:** + +- [ ] Windows: 60 FPS at 5,000+ nodes (verified by automated benchmark) +- [ ] Web (WASM): 60 FPS at 2,000+ nodes (verified by automated benchmark) +- [ ] Android: 60 FPS at 1,500+ nodes (verified by automated benchmark) +- [ ] No memory leaks over 30-minute continuous operation sessions +- [ ] Main thread frame time < 8ms during layout recalculation + +--- + +### 5.2 — Heavy Computation Isolate Offloading + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 5.2.1 | Audit and confirm: Reingold-Tilford layout → background Isolate | ⬜ | | | | | +| 5.2.2 | Audit and confirm: MTOE validation engine → background Isolate | ⬜ | | | | | +| 5.2.3 | Offload JSON/Protobuf serialization → background Isolate | ⬜ | | | | | +| 5.2.4 | Offload PDF rendering → background Isolate | ⬜ | | | | | +| 5.2.5 | Implement `IsolatePool` for managing concurrent background computations | ⬜ | | | | | +| 5.2.6 | Implement progress reporting from Isolates to UI | ⬜ | | | | | +| 5.2.7 | Implement Isolate cancellation for superseded layout requests | ⬜ | | | | | + +**5.2 Acceptance Criteria:** + +- [ ] Main UI thread frame time remains < 8ms during any background computation +- [ ] Isolate cancellation correctly aborts superseded layout requests +- [ ] Progress indicators display for all operations > 500ms + +--- + +### 5.3 — Platform-Specific Hardening + +Windows x64 + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 5.3.1 | Implement multi-window support (multiple UTO workspaces simultaneously) | ⬜ | | | | | +| 5.3.2 | Verify high-DPI scaling at 100%, 125%, 150%, 200% display scaling | ⬜ | | | | | +| 5.3.3 | Implement system tray integration and window state persistence | ⬜ | | | | | +| 5.3.4 | Configure `.msi` installer with registry entries and uninstall support | ⬜ | | | | | +| 5.3.5 | Implement Windows file association for `.uto` project files | ⬜ | | | | | + +Web (WASM/CanvasKit) + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 5.3.6 | Optimize WASM bundle size (tree-shaking, deferred template asset loading) | ⬜ | | | | | +| 5.3.7 | Implement IndexedDB storage quota management and user warnings | ⬜ | | | | | +| 5.3.8 | Implement memory-bounded canvas surface allocation | ⬜ | | | | | +| 5.3.9 | Configure service worker for offline PWA capability | ⬜ | | | | | +| 5.3.10 | Test across Chrome, Edge, and Firefox | ⬜ | | | | | + +Android + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 5.3.11 | Implement battery profiling: reduce Isolate activity when battery < 20% | ⬜ | | | | | +| 5.3.12 | Verify all touch targets ≥ 48×48 dp across all interactive elements | ⬜ | | | | | +| 5.3.13 | Implement Android back-gesture handling for panel navigation | ⬜ | | | | | +| 5.3.14 | Configure `.aab` release build with ProGuard/R8 optimization | ⬜ | | | | | +| 5.3.15 | Test on Android 12, 13, and 14 (tablet and phone form factors) | ⬜ | | | | | + +**5.3 Acceptance Criteria:** + +- [ ] Windows installer installs/uninstalls cleanly; `.uto` file association works +- [ ] Web app functions offline after initial load (PWA service worker active) +- [ ] Android app passes battery profiling: no excessive background drain +- [ ] All touch targets verified ≥ 48×48 dp on Android + +--- + +### 5.4 — Security, Accessibility, & Final QA + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 5.4.1 | Implement classification marking placeholder system (UNCLASSIFIED / FOUO banners) | ⬜ | | | | | +| 5.4.2 | Integrate SQLCipher for data-at-rest database encryption | ⬜ | | | | | +| 5.4.3 | Implement platform keychain key storage (Windows Credential Manager / Android Keystore) | ⬜ | | | | | +| 5.4.4 | Conduct screen reader compatibility audit (Windows Narrator, Android TalkBack) | ⬜ | | | | | +| 5.4.5 | Verify WCAG 2.1 AA contrast ratios for all text elements | ⬜ | | | | | +| 5.4.6 | Verify keyboard-only navigation completeness on Windows/Web | ⬜ | | | | | +| 5.4.7 | Execute E2E test: template instantiation → drag-and-drop → personnel assignment → export | ⬜ | | | | | +| 5.4.8 | Execute E2E test: offline operation → reconnection → delta synchronization | ⬜ | | | | | +| 5.4.9 | Execute E2E test: validation finding detection → resolution → re-validation | ⬜ | | | | | +| 5.4.10 | Conduct load test: 10 simultaneous full BCT templates, 10-minute stability | ⬜ | | | | | + +**5.4 Acceptance Criteria:** + +- [ ] Database encryption verified: raw SQLite file unreadable without key +- [ ] All WCAG 2.1 AA contrast requirements met +- [ ] All E2E tests pass with 100% success rate on all three platforms +- [ ] Load test: 10 simultaneous BCT templates stable for 10 minutes without crash or memory leak + +--- + +### 5.5 — Release Package Assembly + +| # | Task | Status | Assignee | Start Date | End Date | Notes | +|---|---|---|---|---|---|---| +| 5.5.1 | Assemble Windows release: signed `.msi` installer + portable `.exe` archive | ⬜ | | | | | +| 5.5.2 | Assemble Web release: optimized WASM bundle + static hosting configuration | ⬜ | | | | | +| 5.5.3 | Assemble Android release: signed `.aab` (Google Play) + sideload `.apk` | ⬜ | | | | | +| 5.5.4 | Generate release notes (features, known limitations, upgrade instructions) | ⬜ | | | | | +| 5.5.5 | Tag release in version control (`v1.0.0`) | ⬜ | | | | | +| 5.5.6 | Archive build artifacts with SHA-256 checksums | ⬜ | | | | | + +**5.5 Acceptance Criteria:** + +- [ ] All three release packages install and launch correctly on clean target systems +- [ ] SHA-256 checksums verified for all artifacts +- [ ] Release tagged in version control + +--- + +### Phase 5 Exit Criteria + +| Criterion | Status | Verified By | Date | +|---|---|---|---| +| All three platforms meet FPS targets at specified node counts | ⬜ | | | +| All heavy computations confirmed offloaded to background Isolates | ⬜ | | | +| Platform-specific hardening complete (Windows multi-window, Web PWA, Android battery) | ⬜ | | | +| Database encryption integrated | ⬜ | | | +| End-to-end test suite passing on all three platforms | ⬜ | | | +| Release packages assembled and signed for all three platforms | ⬜ | | | + +--- + +## Blockers & Issues Log + +| # | Date Raised | Phase | Task # | Description | Severity | Status | Resolution | Date Resolved | +|---|---|---|---|---|---|---|---|---| +| — | — | — | — | No blockers recorded | — | — | — | — | + +--- + +## Milestone Summary + +| Milestone | Target Week | Deliverable | Status | +|---|---|---|---| +| M1 | End of Week 4 | Compilable multi-platform skeleton + Drift DB + CI pipeline | ⬜ | +| M2 | End of Week 9 | Functional canvas engine with drag-and-drop on Windows and Android | ⬜ | +| M3 | End of Week 14 | All BCT templates instantiable + MIL-STD-2525D symbols rendering | ⬜ | +| M4 | End of Week 19 | Full persistence + real-time MTOE validation + JSON/PDF export | ⬜ | +| M5 | End of Week 24 | Signed release packages for Windows, Web, and Android | ⬜ | + +--- + +## Task Count Summary + +| Phase | Total Tasks | Complete | In Progress | Blocked | Not Started | +|---|---|---|---|---|---| +| Phase 1 | 30 | 0 | 0 | 0 | 30 | +| Phase 2 | 29 | 0 | 0 | 0 | 29 | +| Phase 3 | 34 | 0 | 0 | 0 | 34 | +| Phase 4 | 30 | 0 | 0 | 0 | 30 | +| Phase 5 | 33 | 0 | 0 | 0 | 33 | +| **Total** | **156** | **0** | **0** | **0** | **156** | + +--- + +Document Version: 1.0 | Generated: 2026-08-07 | Companion to: phased_development_plan.md + +Update this document at the start and end of each work session. diff --git a/docs/developer-guide/architecture/overview.md b/docs/developer-guide/architecture/overview.md new file mode 100644 index 0000000..0b22b7d --- /dev/null +++ b/docs/developer-guide/architecture/overview.md @@ -0,0 +1,132 @@ +# Architecture Overview + +## Layered Clean Architecture + +--- + +UTO Manager implements a strict **four-layer clean architecture** that decouples the presentation layer from domain logic and infrastructure concerns. This separation ensures that Army MTOE business rules execute identically regardless of whether the software runs on a Windows command post workstation or an Android tactical tablet. + +--- + +## Layer Diagram + +```text +┌─────────────────────────────────────────────────────────────┐ +│ PRESENTATION LAYER │ +│ CustomPainter / InteractiveViewer / Responsive Shell │ +│ Three-pane UI / Android adaptive layout │ +└──────────────────────────┬──────────────────────────────────┘ + │ (events / state) +┌──────────────────────────▼──────────────────────────────────┐ +│ APPLICATION STATE LAYER │ +│ BLoC / Signals / Use Cases │ +│ Super Drag-and-Drop Pipeline / Command Objects │ +└──────────────────────────┬──────────────────────────────────┘ + │ (domain calls) +┌──────────────────────────▼──────────────────────────────────┐ +│ DOMAIN LAYER │ +│ MTOE Doctrinal Rules Engine / Structural Validation │ +│ Entities / Value Objects / Repository Interfaces │ +└──────────────────────────┬──────────────────────────────────┘ + │ (repository implementations) +┌──────────────────────────▼──────────────────────────────────┐ +│ INFRASTRUCTURE LAYER │ +│ Drift SQLite (Windows/Android) / IndexedDB (Web) │ +│ Protobuf Codecs / Delta Synchronizer / PDF Renderer │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Project Folder Structure + +```text +lib/ +├── domain/ +│ ├── entities/ +│ │ ├── unit_node.dart +│ │ ├── position_slot.dart +│ │ └── personnel_record.dart +│ ├── enums/ +│ │ ├── echelon.dart +│ │ ├── doctrinal_branch.dart +│ │ └── authorized_rank.dart +│ ├── value_objects/ +│ │ └── duty_mos.dart +│ └── repositories/ +│ ├── unit_repository.dart +│ └── personnel_repository.dart +│ +├── application/ +│ ├── blocs/ +│ │ ├── canvas_bloc.dart +│ │ ├── validation_bloc.dart +│ │ └── personnel_bloc.dart +│ └── use_cases/ +│ ├── attach_node_use_case.dart +│ ├── assign_personnel_use_case.dart +│ └── instantiate_template_use_case.dart +│ +├── infrastructure/ +│ ├── database/ +│ │ ├── app_database.dart +│ │ ├── tables/ +│ │ └── daos/ +│ ├── codecs/ +│ │ ├── json_template_codec.dart +│ │ └── protobuf_codec.dart +│ └── sync/ +│ ├── command_event_store.dart +│ └── delta_synchronizer.dart +│ +└── presentation/ + ├── canvas/ + │ ├── uto_canvas_painter.dart + │ ├── drag_overlay_painter.dart + │ └── node_render_model.dart + ├── layout/ + │ ├── reingold_tilford.dart + │ └── quadtree.dart + ├── symbology/ + │ ├── tactical_symbol_painter.dart + │ ├── sidc_resolver.dart + │ └── symbol_cache.dart + └── shell/ + ├── app_shell.dart + ├── left_panel.dart + ├── right_panel.dart + └── status_bar.dart +``` + +--- + +## Key Design Decisions + +### 1. CustomPainter Over Widget Tree + +Standard Flutter layout widgets (`Row`, `Column`, `NestedScrollView`) are inadequate for rendering thousands of hierarchical military elements due to widget tree overhead. The platform uses a bespoke `CustomPainter` engine with direct GPU canvas calls (`drawPath`, `drawParagraph`, `drawRect`), bypassing the widget layer entirely for node rendering. + +### 2. Offline-First Data Model + +All user interactions write directly to the local Drift/SQLite database. The application operates fully without network connectivity. A `DeltaSynchronizer` transmits queued `CommandEvent` records when connectivity is restored, minimizing bandwidth consumption on contested tactical networks. + +### 3. Background Dart Isolates + +Computationally intensive operations run in background Dart Isolates to prevent UI thread blocking: + +- **Reingold-Tilford layout** — Tree positioning for 500+ node formations +- **MTOE validation engine** — Continuous structural rule evaluation +- **JSON/Protobuf serialization** — Large export operations +- **PDF rendering** — Vector organizational chart generation + +### 4. Externalized JSON Templates + +Force structure definitions are stored as JSON schema files loaded at runtime. When Army doctrine changes (e.g., adjusting ISV rifle squad composition), administrators issue updated JSON files without requiring binary recompilation or client updates. + +--- + +## See Also + +- [Clean Architecture Details](clean-architecture.md) +- [State Management](state-management.md) +- [Offline-First Architecture](offline-first.md) diff --git a/docs/developer-guide/index.md b/docs/developer-guide/index.md new file mode 100644 index 0000000..59899c1 --- /dev/null +++ b/docs/developer-guide/index.md @@ -0,0 +1,89 @@ +# Developer Guide + +## UTO Manager — Engineering & Architecture Reference + +--- + +This guide covers the technical architecture, implementation details, and contribution guidelines for engineers building and extending the UTO Manager platform. + +--- + +## In This Guide + +| Section | Description | +|---|---| +| [Architecture Overview](architecture/overview.md) | Layered clean architecture and system design | +| [Domain Model](domain/entities.md) | Core Dart entities, enums, and repository contracts | +| [Canvas Engine](canvas/custom-painter.md) | CustomPainter rendering, viewport culling, layout algorithm | +| [Symbology Engine](symbology/mil-std-2525d.md) | MIL-STD-2525D hybrid rendering pipeline | +| [Database & Persistence](database/drift-schema.md) | Drift schema, DAOs, migrations, offline-first | +| [Validation Engine](validation/mtoe-engine.md) | Real-time MTOE validation in background Isolates | +| [Export Engine](export/json-codec.md) | JSON, Protobuf, and PDF export modules | +| [Performance](performance/repaint-boundaries.md) | RepaintBoundary isolation, Dart Isolates, benchmarks | +| [CI/CD](cicd/pipeline.md) | Multi-platform build pipeline and test gates | +| [Contributing](contributing/workflow.md) | Branch strategy, commit conventions, code standards | + +--- + +## Architecture at a Glance + +```text +[Presentation Layer] + CustomPainter / InteractiveViewer / Responsive Shell + │ + ▼ +[Application State Layer] + BLoC / Signals / Drag-and-Drop Pipeline + │ + ▼ +[Domain Layer] + MTOE Rules Engine / Structural Validation / Entities + │ + ▼ +[Infrastructure Layer] + Drift SQLite / IndexedDB / Protobuf Codecs / Delta Sync +``` + +--- + +## Technology Stack + +| Layer | Technology | +|---|---| +| UI Framework | Flutter 3.x (Dart 3.x) | +| Rendering | CustomPainter + InteractiveViewer | +| State Management | BLoC + Signals | +| Drag-and-Drop | super_drag_and_drop | +| Local Database | Drift (SQLite / IndexedDB) | +| Encryption | SQLCipher | +| Symbology (Web) | milsymbol.js via dart:js_interop | +| Symbology (Native) | path_drawing + SVG assets + LRU cache | +| Background Compute | Dart Isolates | +| Serialization | JSON + Protobuf | +| PDF Export | pdf package | +| Documentation | MkDocs + Material theme | + +--- + +## Development Setup + +```bash +# Clone the repository +git clone https://git.kellsupport.com/uto_manager.git +cd uto_manager + +# Install Flutter dependencies +flutter pub get + +# Run static analysis +flutter analyze + +# Run all tests with coverage +flutter test --coverage + +# Install documentation dependencies +pip install -r docs/requirements.txt + +# Serve documentation locally +mkdocs serve +``` diff --git a/docs/doctrinal-reference/index.md b/docs/doctrinal-reference/index.md new file mode 100644 index 0000000..6105f38 --- /dev/null +++ b/docs/doctrinal-reference/index.md @@ -0,0 +1,44 @@ +# Doctrinal Reference + +## U.S. Army 2026 Force Structure & Symbology Reference + +--- + +This section provides reference material for U.S. Army 2026 doctrine as implemented in UTO Manager, including force structure specifications, MOS reference tables, and MIL-STD-2525D symbology codes. + +--- + +## Sections + +| Section | Description | +|---|---| +| [Force Structures](force-structures/mbct.md) | 2026 BCT organizational structures and composition | +| [MOS Reference](mos/infantry.md) | Military Occupational Specialty codes by branch | +| [MIL-STD-2525D](symbology/overview.md) | Tactical symbology standard reference | + +--- + +## Supported Formation Types + +| Template | Full Name | Primary Vehicle | +|---|---|---| +| MBCT | Mobile Brigade Combat Team | M1301 Infantry Squad Vehicle (ISV) | +| SBCT | Stryker Brigade Combat Team | Stryker ICV (8×8) | +| ABCT | Armored Brigade Combat Team | M1A2 SEPv3 Abrams / M2A3/A4 Bradley | +| CAB-Heavy | Combat Aviation Brigade (Heavy) | AH-64E / UH-60M / CH-47F | +| CAB-Light | Combat Aviation Brigade (Light) | AH-64E / UH-60M / MQ-9A | + +--- + +## MOS Branch Summary + +| Branch | CMF | Key MOS Codes | +|---|---|---| +| Infantry & Maneuver | 11 | 11A, 11B, 15W | +| Medical | 68 | 68W | +| Field Artillery | 13 | 13F, 13D | +| Signal | 25 | 25H, 25B | +| Cyber / EW | 17 | 17E | +| Aviation | 15 / 153 | 15T, 15W, 153A | +| Logistics | 91 / 92 | 91A, 91B, 92A, 92Y | +| Engineer | 12 | 12B | diff --git a/docs/includes/abbreviations.md b/docs/includes/abbreviations.md new file mode 100644 index 0000000..2673184 --- /dev/null +++ b/docs/includes/abbreviations.md @@ -0,0 +1,34 @@ + + + +*[UTO]: Unit Task Organization +*[MTOE]: Modified Table of Organization and Equipment +*[BCT]: Brigade Combat Team +*[MBCT]: Mobile Brigade Combat Team +*[SBCT]: Stryker Brigade Combat Team +*[ABCT]: Armored Brigade Combat Team +*[CAB]: Combat Aviation Brigade +*[MOS]: Military Occupational Specialty +*[SIDC]: Symbol Identification Code +*[BLoC]: Business Logic Component +*[WASM]: WebAssembly +*[LRU]: Least Recently Used +*[ISV]: Infantry Squad Vehicle +*[MDEP]: Multi-Domain Effects Platoon +*[HKP]: Hunter-Killer Platoon +*[C2]: Command and Control +*[TCCC]: Tactical Combat Casualty Care +*[FDC]: Fire Direction Center +*[BAS]: Battalion Aid Station +*[BSB]: Brigade Support Battalion +*[HHC]: Headquarters and Headquarters Company +*[CAB]: Combat Aviation Brigade +*[FSC]: Forward Support Company +*[PWA]: Progressive Web App +*[GPU]: Graphics Processing Unit +*[FFI]: Foreign Function Interface +*[DAO]: Data Access Object +*[ORM]: Object-Relational Mapper +*[CI]: Continuous Integration +*[CD]: Continuous Deployment +*[FPS]: Frames Per Second diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..9a8d4d7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,72 @@ +# UTO Manager Documentation + +## Flutter-Based Military Unit Task Organization Enterprise System + +### U.S. Army 2026 Doctrine — Cross-Platform Command & Control Application + +--- + +Welcome to the **UTO Manager** documentation. Use the navigation tabs above to find what you need. + +--- + +## Documentation Sections + +
+ +- :material-book-open-variant:{ .lg .middle } **User Guide** + + --- + + Step-by-step instructions for planners and operators using UTO Manager to build, visualize, and validate unit task organizations. + + [:octicons-arrow-right-24: User Guide](user-guide/index.md) + +- :material-code-braces:{ .lg .middle } **Developer Guide** + + --- + + Architecture deep-dives, API references, and contribution guidelines for engineers building and extending the platform. + + [:octicons-arrow-right-24: Developer Guide](developer-guide/index.md) + +- :material-shield-star:{ .lg .middle } **Doctrinal Reference** + + --- + + U.S. Army 2026 force structure specifications, MOS reference tables, and MIL-STD-2525D symbology reference. + + [:octicons-arrow-right-24: Doctrinal Reference](doctrinal-reference/index.md) + +- :material-note-text:{ .lg .middle } **Release Notes** + + --- + + Version history, feature summaries, known limitations, and upgrade instructions. + + [:octicons-arrow-right-24: Release Notes](release-notes/index.md) + +
+ +--- + +## Quick Links + +| Resource | Description | +|---|---| +| [Installation](user-guide/getting-started/installation.md) | Set up UTO Manager on Windows, Web, or Android | +| [Quick Start](user-guide/getting-started/quick-start.md) | Create your first unit task organization in 5 minutes | +| [MBCT Template](user-guide/templates/mbct.md) | Mobile Brigade Combat Team template guide | +| [Architecture Overview](developer-guide/architecture/overview.md) | Clean architecture and layered design | +| [MOS Reference](doctrinal-reference/mos/infantry.md) | Military Occupational Specialty reference tables | +| [MIL-STD-2525D](doctrinal-reference/symbology/overview.md) | Tactical symbology reference | + +--- + +## About This Project + +UTO Manager is a cross-platform C2 application built with **Flutter** targeting Windows x64, Web (WASM/CanvasKit), and Android from a single Dart codebase. The system enforces U.S. Army MTOE doctrinal rules in real time, supporting formations from individual soldier positions up to multi-domain Brigade Combat Teams. + +**Current Version:** Pre-release (Phase 1 — Architecture & Data Foundations) + +**Project Repository:** [git.kellsupport.com/uto_manager](https://git.kellsupport.com/uto_manager) diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js new file mode 100644 index 0000000..88c5806 --- /dev/null +++ b/docs/javascripts/mathjax.js @@ -0,0 +1,22 @@ +/* MathJax configuration for UTO Manager documentation */ +/* Enables rendering of doctrinal formulas (viewport culling, layout algorithms) */ + +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; + +document$.subscribe(() => { + MathJax.startup.output.clearCache(); + MathJax.typesetClear(); + MathJax.texReset(); + MathJax.typesetPromise(); +}); diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md new file mode 100644 index 0000000..a1fe7f5 --- /dev/null +++ b/docs/release-notes/index.md @@ -0,0 +1,21 @@ +# Release Notes + +## UTO Manager Version History + +--- + +| Version | Date | Status | +|---|---|---| +| [v1.0.0](v1.0.0.md) | TBD | 🔵 In Development | + +--- + +## Roadmap + +| Milestone | Target | Deliverable | +|---|---|---| +| M1 — End of Week 4 | TBD | Compilable multi-platform skeleton + Drift DB + CI pipeline | +| M2 — End of Week 9 | TBD | Functional canvas engine with drag-and-drop on Windows and Android | +| M3 — End of Week 14 | TBD | All BCT templates instantiable + MIL-STD-2525D symbols rendering | +| M4 — End of Week 19 | TBD | Full persistence + real-time MTOE validation + JSON/PDF export | +| M5 — End of Week 24 | TBD | Signed release packages for Windows, Web, and Android | diff --git a/docs/release-notes/v1.0.0.md b/docs/release-notes/v1.0.0.md new file mode 100644 index 0000000..b9f6fe8 --- /dev/null +++ b/docs/release-notes/v1.0.0.md @@ -0,0 +1,59 @@ +# v1.0.0 — Initial Release + +## Status: 🔵 In Development + +**Target:** End of Week 24 + +--- + +## Planned Features + +### Core Platform + +- Cross-platform Flutter application targeting Windows x64, Web (WASM), and Android +- GPU-accelerated `CustomPainter` canvas engine with viewport culling +- 60 FPS rendering at 5,000+ nodes (Windows), 2,000+ (Web), 1,500+ (Android) + +### Organizational Modeling + +- Complete domain model: `UnitNode`, `PositionSlot`, `PersonnelRecord` +- MOS validation across all functional branches (Infantry, Medical, Fires, Signal, Cyber/EW, Aviation, Logistics, Engineer) +- 2026 doctrinal templates: MBCT, SBCT, ABCT, CAB-Heavy, CAB-Light + +### Visual Canvas + +- Reingold-Tilford hierarchical tree layout algorithm +- Quadtree spatial index for hit-testing and drag proximity queries +- Cross-platform drag-and-drop re-parenting with doctrinal validation highlights +- MIL-STD-2525D tactical symbology rendering + +### Persistence & Validation + +- Drift/SQLite offline-first persistence with IndexedDB on Web +- Real-time MTOE validation engine (MOS mismatch, rank mismatch, vacant leadership, structural violations) +- Delta synchronization for contested network environments +- SQLCipher data-at-rest encryption + +### Export + +- JSON export/import with doctrinal validation +- Protobuf binary export +- Vector PDF organizational chart export + +### Platform-Specific + +- Windows: multi-window, high-DPI scaling, `.msi` installer, `.uto` file association +- Web: PWA offline capability, IndexedDB quota management +- Android: battery profiling, touch-optimized targets (48×48 dp minimum) + +--- + +## Known Limitations + +*To be documented upon release.* + +--- + +## Upgrade Instructions + +*Initial release — no upgrade path required.* diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..10b763a --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,9 @@ +# MkDocs and plugins for UTO Manager documentation +# Install with: pip install -r docs/requirements.txt + +mkdocs>=1.6.0 +mkdocs-material>=9.5.0 +mkdocs-material-extensions>=1.3.0 +pymdown-extensions>=10.7.0 +mkdocs-minify-plugin>=0.8.0 +mike>=2.0.0 diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..6ed4075 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,43 @@ +/* UTO Manager — MkDocs Material Theme Custom Styles */ + +/* Military-themed accent for admonition blocks */ +.md-typeset .admonition.military, +.md-typeset details.military { + border-color: #1a3a5c; +} + +.md-typeset .military > .admonition-title, +.md-typeset .military > summary { + background-color: rgba(26, 58, 92, 0.1); + border-color: #1a3a5c; +} + +.md-typeset .military > .admonition-title::before, +.md-typeset .military > summary::before { + background-color: #1a3a5c; +} + +/* Status badge styling for development status tables */ +.status-complete { color: #2e7d32; font-weight: bold; } +.status-in-progress { color: #1565c0; font-weight: bold; } +.status-not-started { color: #757575; } +.status-blocked { color: #c62828; font-weight: bold; } + +/* Monospace styling for MOS codes */ +.mos-code { + font-family: 'Roboto Mono', monospace; + background-color: var(--md-code-bg-color); + padding: 0.1em 0.3em; + border-radius: 0.2em; + font-size: 0.85em; +} + +/* Canvas diagram styling */ +.canvas-diagram { + font-family: 'Roboto Mono', monospace; + background-color: var(--md-code-bg-color); + padding: 1em; + border-radius: 0.4em; + overflow-x: auto; + white-space: pre; +} diff --git a/docs/user-guide/getting-started/installation.md b/docs/user-guide/getting-started/installation.md new file mode 100644 index 0000000..a8ab2c6 --- /dev/null +++ b/docs/user-guide/getting-started/installation.md @@ -0,0 +1,69 @@ +# Installation + +## System Requirements & Installation Guide + +--- + +## Windows x64 + +### System Requirements + +| Component | Minimum | Recommended | +|---|---|---| +| OS | Windows 10 (64-bit) | Windows 11 (64-bit) | +| RAM | 4 GB | 8 GB+ | +| Storage | 500 MB | 1 GB+ | +| Display | 1280×720 | 1920×1080 or higher | +| GPU | DirectX 11 compatible | DirectX 12 / Vulkan | + +### Installation Steps + +1. Download the latest `.msi` installer from the [releases page](https://git.kellsupport.com/uto_manager/releases) +2. Run the installer and follow the on-screen prompts +3. Launch **UTO Manager** from the Start Menu or desktop shortcut +4. On first launch, the application will initialize the local database + +--- + +## Web (Browser) + +### Supported Browsers + +| Browser | Minimum Version | Notes | +|---|---|---| +| Google Chrome | 112+ | Recommended; full WASM support | +| Microsoft Edge | 112+ | Full WASM support | +| Mozilla Firefox | 120+ | Supported; verify WASM performance | + +### Access + +Navigate to the hosted URL provided by your system administrator. No installation required. + +!!! note "Offline Capability" + After the first load, UTO Manager functions as a Progressive Web App (PWA) and can operate offline using locally cached data. + +--- + +## Android + +### System Requirements + +| Component | Minimum | Recommended | +|---|---|---| +| Android Version | Android 12 | Android 13 or 14 | +| RAM | 3 GB | 6 GB+ | +| Storage | 300 MB | 500 MB+ | +| Screen | Phone (5"+) | Tablet (10"+) | + +### Installation Steps + +1. Download the `.apk` from the [releases page](https://git.kellsupport.com/uto_manager/releases) +2. Enable **Install from Unknown Sources** in Android Settings if sideloading +3. Install the `.apk` and launch **UTO Manager** + +--- + +## Next Steps + +- [Quick Start Guide](quick-start.md) — Build your first UTO in 5 minutes +- [Interface Overview](interface-overview.md) — Learn the three-pane workspace layout diff --git a/docs/user-guide/getting-started/interface-overview.md b/docs/user-guide/getting-started/interface-overview.md new file mode 100644 index 0000000..7f2a267 --- /dev/null +++ b/docs/user-guide/getting-started/interface-overview.md @@ -0,0 +1,101 @@ +# Interface Overview + +## Three-Pane Workspace Layout + +--- + +## Desktop Layout (Windows / Web) + +```text +┌────────────────────────────────────────────────────────────────────────────┐ +│ Header: Echelon Selector | Doctrinal Mode | Export Tools │ +├──────────────────┬─────────────────────────────────────┬───────────────────┤ +│ Left Panel: │ Central Canvas Workspace │ Right Panel: │ +│ Template Palette │ (Pan / Zoom / Drag-and-Drop) │ Node Inspector │ +│ │ │ │ +│ - MBCT Template │ [Brigade HQ] │ - Unit ID & Name │ +│ - SBCT Template │ │ │ - Assigned MOS │ +│ - ABCT Template │ ├── [Infantry Bn] │ - Personnel │ +│ - CAB Template │ │ └── [Rifle Platoon] │ - Readiness │ +│ - Echelon Blocks │ └── [Artillery Bn] │ - Findings │ +├──────────────────┴─────────────────────────────────────┴───────────────────┤ +│ Status Bar: Scale Factor | Active Node Count | MTOE Validation Status │ +└────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Panel Descriptions + +### Application Header + +| Control | Function | +|---|---| +| Echelon Selector | Filter canvas display by echelon level | +| Doctrinal Mode | Toggle between 2026 MBCT / SBCT / ABCT / CAB modes | +| Export Tools | Open export dialog (JSON / Protobuf / PDF) | + +### Left Panel — Template Palette + +The collapsible left sidebar contains drag-and-drop building blocks: + +- **2026 Brigade Templates** — Complete pre-configured formations (MBCT, SBCT, ABCT, CAB-Heavy, CAB-Light) +- **Echelon Blocks** — Individual battalion, company, platoon, squad, and team frameworks +- **Duty Position Slots** — Standalone position slots across all branches (Infantry, Medical, Signal, EW, UAV, Supply) + +### Central Canvas Workspace + +The main interactive area hosting the infinite organizational graph. Features: + +- **Pan** — Click and drag on empty canvas space +- **Zoom** — Mouse wheel (desktop) or pinch gesture (Android) +- **Node Selection** — Click any node to select; Shift+click for multi-select +- **Box Selection** — Click and drag on empty space to draw a selection rectangle +- **Drag-and-Drop** — Drag nodes to re-parent within the hierarchy + +### Right Panel — Node Inspector + +Context-sensitive panel that updates when a node is selected: + +- **Unit Information** — Unit ID, designation, echelon, doctrinal branch +- **Position Slots** — List of authorized duty positions with fill status +- **Personnel Assignment** — Search and assign soldier records to slots +- **Equipment** — Organic equipment and Line Item Numbers (LIN) +- **Readiness Status** — Manning percentage and operational readiness toggle +- **Validation Findings** — Active MTOE findings for the selected node + +### Status Bar + +| Indicator | Description | +|---|---| +| Scale Factor | Current canvas zoom level (e.g., `1.0×`, `0.5×`) | +| Active Node Count | Total nodes currently rendered on canvas | +| MTOE Validation | Aggregate finding counts: 🔴 Critical / 🟡 Warning / 🔵 Advisory | + +--- + +## Android Layout + +On Android, the three-pane layout adapts to a mobile-optimized configuration: + +- **Left Panel** → Navigation Drawer (swipe from left edge or tap ☰) +- **Right Panel** → Bottom Sheet Inspector (tap any node to open) +- **Right-click menus** → Tap-and-hold radial menus (200ms press) +- **Keyboard shortcuts** → Not available; use touch gestures + +--- + +## Keyboard Shortcuts (Windows / Web) + +| Shortcut | Action | +|---|---| +| `Ctrl+Z` | Undo last operation | +| `Ctrl+Y` | Redo | +| `Ctrl+F` | Search nodes | +| `Ctrl+D` | Duplicate selected subtree | +| `Ctrl+S` | Save current workspace | +| `Ctrl+E` | Open export dialog | +| `Delete` | Remove selected node | +| `Escape` | Deselect / cancel drag | +| `Ctrl+A` | Select all nodes | +| `Ctrl+0` | Reset zoom to 100% | diff --git a/docs/user-guide/getting-started/quick-start.md b/docs/user-guide/getting-started/quick-start.md new file mode 100644 index 0000000..ad06a46 --- /dev/null +++ b/docs/user-guide/getting-started/quick-start.md @@ -0,0 +1,83 @@ +# Quick Start + +## Build Your First Unit Task Organization in 5 Minutes + +--- + +## Step 1: Launch UTO Manager + +Open UTO Manager on your platform of choice. You will be presented with the three-pane workspace: + +- **Left Panel** — Doctrinal template palette +- **Central Canvas** — Interactive organizational chart workspace +- **Right Panel** — Node inspector and position editor + +--- + +## Step 2: Load a Doctrinal Template + +1. In the **Left Panel**, locate the **2026 Templates** section +2. Click or drag the **MBCT** (Mobile Brigade Combat Team) template onto the canvas +3. The system will instantiate the complete brigade structure — approximately 500+ nodes — and display it on the canvas + +!!! tip "Template Instantiation Time" + Full BCT templates typically load in under 2 seconds. A progress indicator will display for larger formations. + +--- + +## Step 3: Navigate the Canvas + +| Action | Windows/Web | Android | +|---|---|---| +| Pan | Click + drag on empty canvas | One-finger drag | +| Zoom | Mouse wheel | Pinch gesture | +| Select node | Left-click | Tap | +| Open context menu | Right-click | Tap and hold (200ms) | + +--- + +## Step 4: Inspect a Unit Node + +1. Click any unit node on the canvas (e.g., a Rifle Platoon) +2. The **Right Panel** updates to show: + - Unit designation and echelon + - Assigned personnel and MOS + - Readiness status + - Active MTOE validation findings + +--- + +## Step 5: Assign a Soldier + +1. Select a position slot node (e.g., **Platoon Leader**) +2. In the Right Panel, click **Personnel Search** +3. Search by name or MOS code (e.g., `11A`) +4. Select a soldier record to assign them to the slot +5. The validation engine will immediately check for MOS and rank compliance + +--- + +## Step 6: Re-parent a Unit (Drag and Drop) + +1. Click and hold a unit node (e.g., a Rifle Squad) +2. Drag it toward a new parent unit +3. Valid drop targets highlight **green**; invalid targets highlight **red** +4. Release to complete the re-parenting operation +5. Use **Ctrl+Z** (Windows/Web) to undo if needed + +--- + +## Step 7: Export the Organizational Chart + +1. Click **Export** in the application header +2. Select format: **JSON**, **Protobuf**, or **PDF** +3. Choose scope: **Full Tree** or **Selected Subtree** +4. Click **Export** and choose a save location + +--- + +## Next Steps + +- [Interface Overview](interface-overview.md) — Detailed workspace layout reference +- [Working with Templates](../templates/overview.md) — All five 2026 BCT templates +- [MTOE Validation](../validation/mtoe-validation.md) — Understanding validation findings diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md new file mode 100644 index 0000000..4f3b104 --- /dev/null +++ b/docs/user-guide/index.md @@ -0,0 +1,37 @@ +# User Guide + +## UTO Manager — Operator & Planner Reference + +--- + +This guide covers everything a military planner or operator needs to use UTO Manager effectively — from initial installation through building, validating, and exporting complete unit task organizations. + +--- + +## In This Guide + +| Section | Description | +|---|---| +| [Getting Started](getting-started/installation.md) | Installation, prerequisites, and first launch | +| [Working with Templates](templates/overview.md) | Loading and customizing 2026 doctrinal templates | +| [Canvas & Navigation](canvas/pan-zoom.md) | Navigating the interactive organizational canvas | +| [Personnel Management](personnel/assigning-soldiers.md) | Assigning soldiers to duty positions | +| [Validation & Readiness](validation/mtoe-validation.md) | Understanding and resolving MTOE validation findings | +| [Export & Import](export/json-export.md) | Exporting organizational charts and data | +| [Platform Guides](platforms/windows.md) | Platform-specific features and tips | + +--- + +## Supported Platforms + +=== "Windows" + + Full three-pane workstation layout with keyboard shortcuts, multi-window support, and precision mouse controls. + +=== "Web" + + Browser-based access via WebAssembly. Matches the desktop layout with responsive panel toggles. + +=== "Android" + + Touch-optimized layout with navigation drawer, bottom-sheet inspector, and haptic drag feedback. diff --git a/master_development_plan.md b/master_development_plan.md new file mode 100644 index 0000000..d861b42 --- /dev/null +++ b/master_development_plan.md @@ -0,0 +1,87 @@ +Master Development Plan: Flutter-Based Military Unit Task Organization Enterprise System (U.S. Army 2026 Doctrine)Executive Architectural Strategy & Cross-Platform Engine DesignThe modern military operational environment demands command and control (C2) software capable of rapidly modeling, manipulating, and displaying unit task organizations (UTOs) that conform to evolving force structures. The objective of this development plan is to establish the software architecture, technical specifications, domain data models, and deployment roadmap for a cross-platform application developed in Flutter. The platform creates, visualizes, and validates U.S. Army unit task organizations starting at the individual soldier position level and building up to multi-domain brigade formations. The application targets three primary operating environments: Microsoft Windows x64 desktop, modern web browsers via WebAssembly and CanvasKit, and mobile devices running Android.To achieve native operational performance across these diverse targets from a single Dart code base, the system relies on a multi-tiered layered clean architecture integrated with a reactive state management paradigm. Flutter's underlying rendering model, which utilizes the Impeller engine on native platforms and CanvasKit on the web, allows for consistent low-level GPU drawing routines. This design separates platform-specific visual rendering from domain validation logic, ensuring that Army Modified Table of Organization and Equipment (MTOE) business rules execute identically regardless of whether the software runs on a command post Windows workstation or an Android tactical tablet.Platform TargetPrimary Deployment MechanismTarget Performance BaselinePlatform-Specific Integration RequirementsWindows x64Native Executable (.msi / .exe)60 FPS under 5,000+ active graph nodesFull keyboard shortcut integration, multi-window support, precision mouse wheel pan/zoom, high-DPI scaling.WebWebAssembly (WASM) / CanvasKit60 FPS under 2,000+ active graph nodesOptimized asset loading, IndexedDB persistence, memory-bounded canvas surface allocation.AndroidNative Package (.apk / .aab)60 FPS under 1,500+ active graph nodesTouch-optimized gesture targets, drag threshold haptics, responsive bottom-sheet inspectors, battery profiling.The technical foundation decouples the presentation layer from underlying data persistence. The architecture employs a state management approach using reactive primitives (such as BLoC or Signals) to broadcast atomic state changes across UI components. When a planner moves an individual position slot or an entire maneuver platoon across the visual workspace, the state layer processes the interaction as a structural transaction. The transaction evaluates unit attachment rules, checks command relationships, updates spatial relationships, and notifies the visual canvas without triggering full widget tree rebuilds.[Presentation Layer: CustomPainter / InteractiveViewer / Responsive Shell] + │ + ▼ +[Application State Layer: BLoC / Signals / Super Drag-and-Drop Pipeline] + │ + ▼ +[Domain Layer: MTOE Doctrinal Rules Engine / Structural Validation] + │ + ▼ +[Infrastructure Layer: Drift SQLite / IndexedDB / Protobuf Codecs] +Cross-platform drag-and-drop interactions require careful handling to bridge desktop mouse interactions and mobile touch events. While standard Flutter gesture detectors handle basic internal drag events, complex cross-component canvas dragging across different viewports is implemented using specialized abstraction wrappers like super_drag_and_drop. This ensures that drag payloads—containing unit identifiers, subordinate hierarchies, and associated equipment data—retain structural integrity during movement across the organizational workspace.Interactive Visual Canvas Architecture & Visual Drag-and-Drop SubsystemRendering thousands of hierarchical military elements—from a four-man infantry fire team to a 4,500-soldier Brigade Combat Team—requires a visual graph engine optimized for low-latency spatial transformations. Standard Flutter layout widgets like NestedScrollView, Row, or Column are inadequate for large dynamic diagrams due to the rendering overhead of heavy widget trees. Consequently, the platform's visualization engine uses a hybrid architectural approach combining Flutter's low-level CustomPainter API with tailored spatial indexing.Visual Engine StrategyCore Architectural ImplementationScalability ThresholdLatency & Performance ProfilePackage-Based (diagram_editor / graph_edit)Pre-built node widgets managed by interactive controllers and built-in serialization codecs.500 – 1,000 active nodes before frame dropping occurs.Fast initial development velocity; frame rates decrease when rendering large, fully populated brigade trees.Bespoke CustomPainter EngineDirect GPU canvas drawing calls (drawPath, drawParagraph, drawRect) bypassing the Widget layer.10,000+ active nodes using viewport spatial culling.Maximum rendering performance; requires custom code for viewport matrices, node hit testing, and collision routing.The bespoke canvas engine uses a custom viewport management layer wrapping a CustomPainter instance inside a multi-touch InteractiveViewer. Viewport transformations (pan offsets and scale factors) are maintained in a 4x4 matrix ($M$). To maintain a consistent 60 FPS frame rate when rendering large formations, the painter executes spatial culling on every paint pass. The engine calculates the visible canvas bounding box by multiplying the screen dimensions ($S$) by the inverse transformation matrix ($M^{-1}$):$$\text{Viewport}_{\text{visible}} = M^{-1} \times S$$Nodes and parent-child connection lines falling outside this calculated bounding box are skipped during the paint() execution pass, avoiding unnecessary GPU rasterization and text layout computations.Organizational visual layouts strictly enforce standardized military hierarchical tree structures using an adapted Reingold-Tilford tree layout algorithm. The position of any node $N$ at echelon level $L$ is calculated dynamically based on subordinate subtree widths, ensuring clean horizontal separation across functional branches (Maneuver, Fires, Reconnaissance, Engineer, Sustainment) and vertical alignment across echelons (Brigade, Battalion, Company, Platoon, Squad, Team, Individual Position).[Brigade Headquarters (O-6)] + │ + ├─── [Infantry Battalion (O-5)] ─── [Rifle Company (O-3)] ─── [Rifle Platoon (O-2)] + │ │ + │ └─── [Rifle Squad (E-6)] + │ │ + │ ├─── [Alpha Team Leader (E-5)] + │ │ ├─── Automatic Rifleman (E-4) + │ │ ├─── Grenadier (E-4) + │ │ └─── Rifleman (E-3) + │ └─── [Bravo Team Leader (E-5)] + │ ├─── Combat Medic (E-4) + │ ├─── sUAS Drone Operator (E-4) + │ └─── Rifleman (E-3) + │ + └─── [Field Artillery Battalion (O-5)] +The visual drag-and-drop re-parenting engine follows a deterministic event state machine:Selection and Payload Isolation: Initiating a drag gesture captures the target node identifier, isolates its complete subordinate subtree, and extracts it into an overlay rendering layer.Spatial Collision and Validation: As the dragged node moves across the workspace, the engine executes spatial proximity queries against a Quadtree spatial index containing candidate parent nodes.Doctrinal Relationship Evaluation: The domain engine evaluates proposed parent-child connections against Army structural rules. Attaching a Rifle Squad to an Infantry Platoon renders a green target highlight, whereas attempting to attach a Fire Team directly to a Brigade Headquarters displays an invalid red indicator unless designated as a detached element.Drop Execution and Re-indexing: Releasing the node executes a re-parenting command, updates relational keys in the local store, triggers the Reingold-Tilford layout recalculation, and notifies the visual painter via optimized shouldRepaint calls.Military Domain Model & Expanded Personnel Position SyntaxThe platform models military task organizations down to individual soldier positions across all Combat Arms, Combat Support (CS), and Combat Service Support (CSS) Career Management Fields (CMFs). The software structures formations around Military Occupational Specialties (MOS), pay grades, leadership responsibilities, and Line Item Numbers (LIN) defined by Army doctrine.The domain model represents an individual soldier as a personnel record that fills an authorized position slot within a specific organizational unit. A unit (such as a Rifle Squad, Medical Evacuation Section, or Signal Network Platoon) contains a collection of position slots and subordinate elements.Domain AttributeData TypeValidation ConstraintsOperational DescriptionUnit IDUUID v4Non-null, unique keyUnique database identifier for the operational formation.EchelonEnumBrigade, Battalion, Company, Platoon, Section, Squad, TeamTactical command level governing hierarchy rules.Doctrinal BranchEnumInfantry, Medical, Fires, Signal, Cyber/EW, Aviation, LogisticsFunctional branch governing duty slot requirements.Position TitleStringStandardized military title dictionaryOfficial duty title (e.g., "Platoon Leader", "Combat Medic Specialist").Duty MOSStringStandardized 3-character/digit codeRequired specialty code (e.g., "11B", "68W", "13F", "25H", "17E").Authorized RankEnumE-1 through E-9, W-1 through W-5, O-1 through O-10Required pay grade for the duty slot.Key Leader FlagBooleanTrue / FalseIdentifies primary command nodes for command availability checks.Assigned PersonnelObject (Optional)Single active assignment limitLinks an individual soldier record to the authorized slot.Individual position definitions within the system populate a multi-branch dictionary representing combined-arms force structures:[Individual Personnel Record] ──(Fills 0..1)──> [Authorized Position Slot] ──(Belongs to)──> [Unit Node] + │ + (Assigned Duty MOS) + │ + ▼ + [MTOE Specialty Standard] +Core Duty Positions Across Functional BranchesInfantry & Tactical Maneuver:Platoon Leader (MOS 11A / O-2/O-1): Directs tactical maneuver, fires, and force protection for the platoon.Platoon Sergeant (MOS 11B / E-7): Senior non-commissioned officer managing logistics, soldier welfare, and tactical movement execution.Squad Leader (MOS 11B / E-6): Leads a 9-soldier maneuver element.Team Leader (MOS 11B / E-5): Directs a 4-soldier tactical fire team.Automatic Rifleman (MOS 11B / E-4): Operates primary automatic weapon systems (e.g., XM250 NGSW-AR).Grenadier (MOS 11B / E-4/E-3): Operates area-denial grenade launcher systems.Rifleman (MOS 11B / E-3/E-2): Core dismounted combatant equipped with the XM7 service rifle.Medical & Health Services (CMF 68):Combat Medic Specialist (MOS 68W / E-4/E-5): Attached to maneuver platoons or organic to battalion medical platoons; provides immediate tactical combat casualty care (TCCC), point-of-injury triage, and battlefield stabilization.Medical Evacuation NCO (MOS 68W / E-6): Coordinates ground ambulance (AMPV/M113) or air ambulance (HH-60M) medevac assets within the Brigade Support Battalion (BSB) or Aviation Battalion.Treatment NCO (MOS 68W / E-6): Operates Role 1/Role 2 Battalion Aid Stations (BAS) to process casualties.Field Artillery & Fire Support (CMF 13):Joint Fire Support Specialist / NCO (MOS 13F / E-4 to E-6): Organic to field artillery target acquisition elements but forward-deployed with maneuver companies and platoons to call for, adjust, and coordinate artillery, mortar, and close air support fires.Field Artillery Automated Tactical Data System (FAATDS) Operator (MOS 13D / E-4): Computes firing data at battery/battalion Fire Direction Centers (FDC).Signal & Communications Network (CMF 25):Network Communication Systems Specialist (MOS 25H / E-4/E-5): Installs, operates, and maintains tactical satellite terminals, line-of-sight communications, and IP network backbones at company, battalion, and brigade command posts.Cyber & IT Specialist (MOS 25B / E-4/E-5): Configures tactical tactical router stacks, battle management software, and command post servers.Electromagnetic Warfare & Cyber (CMF 17):Electromagnetic Warfare Specialist (MOS 17E / E-4 to E-6): Assigned to Multi-Domain Effects Platoons (MDEP) and brigade electronic warfare sections; executes direction-finding, electronic attack, GPS spoofing mitigation, and electromagnetic spectrum monitoring.Unmanned Aerial Systems & Robotics (CMF 15 / Multi-Branch):sUAS / FPV Drone Operator (MOS 15W or 11B/19D with sUAS Certification / E-4/E-5): Serves in Hunter-Killer Platoons (HKP) and company sUAS teams; operates short/medium-range reconnaissance drones and First-Person View (FPV) loitering munitions.Tactical UAS Operator (MOS 15W / E-4/E-5): Operates higher-echelon unmanned aircraft (e.g., MQ-9A Reaper or launched effects) within Combat Aviation Brigades.Logistics, Supply, & Ordnance (CMF 91 / 92):Unit Supply Specialist / NCO (MOS 92Y / E-4 to E-6): Manages unit MTOE property accounts, coordinates Class I (rations), Class V (ammunition), and Class IX (repair parts) supply distribution within Forward Support Companies (FSC).Automated Logistical Specialist (MOS 92A / E-4): Manages supply warehouse operations at the Brigade Support Battalion.Wheeled / Tracked Vehicle Mechanic (MOS 91B / 91A / E-4/E-5): Executes battlefield maintenance and recovery for ISV, Stryker, Bradley, and Abrams vehicle fleets.Combat Engineers (CMF 12):Combat Engineer (MOS 12B / E-4 to E-6): Conducts obstacle breaching, route clearance, minefield emplacement, and urban mobility tasks within Sapper platoons.Validation logic in the domain layer runs continuously to identify structural anomalies. The engine flags MOS misalignments when a soldier's primary MOS does not match the authorized slot code (e.g., a 11B assigned to a 68W medic slot). It highlights rank mismatches, vacant leadership slots, and missing critical support roles (such as a maneuver platoon lacking an attached 68W medic or 13F fire support specialist), ensuring complete operational readiness visibility.Doctrinal Unit Templates (2026 / Army 2030 Baseline)The application includes pre-configured, standardized doctrinal templates representing the U.S. Army's 2026 force structures. These templates allow planners to instantiate complete, structurally accurate combined-arms formations in a single action. [Brigade Combat Team / Brigade] + │ + ┌──────────────────┬───────────────────┼───────────────────┬──────────────────┐ + │ │ │ │ │ +[Maneuver Bns (x3)] [Cavalry Sqn] [Field Artillery Bn] [Brigade Engineer Bn] [Brigade Support Bn] +Mobile Brigade Combat Team (MBCT)In accordance with Army modernization directives, standard Infantry Brigade Combat Teams (IBCTs) transition to Mobile Brigade Combat Teams (MBCTs). The MBCT addresses light infantry mobility constraints by integrating the M1301 Infantry Squad Vehicle (ISV) across maneuver elements.MBCT Rifle Squad Architecture: Structured around the "Squad as a System" (SaaS) concept, the MBCT rifle squad comprises 9 dismounted soldiers optimized to deploy from a single ISV platform. The squad consists of 1 Squad Leader (E-6), 2 Team Leaders (E-5), 2 Automatic Riflemen equipped with the XM250 Next Generation Squad Weapon-Automatic Rifle (NGSW-AR), 2 Grenadiers equipped with XM7 rifles and M320 launchers, 1 Rifleman/sUAS Drone Operator, and 1 Rifleman.MBCT Rifle Platoon Structure: Contains a Platoon Headquarters (Platoon Leader O-2/O-1, Platoon Sergeant E-7, Radio Operator 25H/E-3, attached Combat Medic 68W/E-4, attached Fire Support NCO 13F/E-6), three 9-soldier Rifle Squads, and an integrated weapons section. Tactical ground movement is provided by an organic fleet of ISVs.Multi-Domain Additions: Modernized MBCT templates include the Multi-Domain Effects Platoon (MDEP), which provides electronic warfare (17E), counter-unmanned aerial systems (C-sUAS), and electromagnetic spectrum operations. Hunter-Killer Platoons (HKPs) combine small unmanned aerial systems (sUAS) with precision targeting assets.Stryker Brigade Combat Team (SBCT)The SBCT serves as the Army's medium combined-arms force, balancing rapid operational deployment with dismounted infantry capability.Maneuver Element: Comprises three Stryker Infantry Battalions, each organized with a Headquarters and Headquarters Company (HHC) containing organic medical platoons (68W), signal sections (25H), and sniper sections.Cavalry Reconnaissance Squadron: Features an HHT, three Stryker Cavalry Troops, and an Anti-Tank Troop equipped with 9 Stryker Anti-Tank Guided Missile (ATGM) vehicles.Field Artillery & Sustainment: Contains a Field Artillery Battalion with three batteries of M777A2 155mm towed howitzers (24 tubes total), a Brigade Engineer Battalion (BEB) containing signal (25H), military intelligence, and combat engineer (12B) companies, and a Brigade Support Battalion (BSB) for medical, distribution, and maintenance execution.Armored Brigade Combat Team (ABCT)The post-2023 / 2026 ABCT structure standardizes three Combined Arms Battalions (CABs) to balance heavy armor firepower with mechanized infantry dismounts.Combined Arms Battalions (x3): Formed as two Armor-Heavy CABs and one Infantry-Heavy CAB. Armor-Heavy CABs contain an HHC, two Tank Companies (14 M1A2 SEPv3 Abrams tanks each), and one Mechanized Infantry Company (14 M2A3/A4 Bradley IFVs). HHC elements integrate Battalion Medical Platoons (68W), Mechanic Sections (91A/91B), and Scout Platoons.Armored Cavalry Squadron: Contains an HHT, three Armored Cavalry Troops (equipped with Bradley Fighting Vehicles and JLTVs), and one organic Tank Troop (14 M1A2 Abrams).Artillery & Engineering: Supported by a Field Artillery Battalion with three batteries of M109A7 Paladin 155mm self-propelled howitzers (18 total systems) and a Brigade Engineer Battalion providing Sapper platoons (12B) directly to each CAB.Combat Aviation Brigade (CAB)Under the Army 2030 force design, Combat Aviation Brigades were streamlined through the divestment of standalone Air Cavalry Squadrons in FY2025/2026. CAB structures are organized into Heavy and Light divisional aviation profiles.Heavy Combat Aviation Brigade: Configured with an Attack Aviation Battalion (24 AH-64E Apache Guardian helicopters, pilots 153A, crew chiefs 15T), an Assault Helicopter Battalion (30 UH-60M Black Hawks, 12 CH-47F Chinooks), an Air Ambulance Company (15 HH-60M medevac helicopters operated by 68W flight medics and 153A aviators), and an Aviation Support Battalion (ASB) for intermediate maintenance (15B/15D/15G) and supply distribution (92Y).Light Combat Aviation Brigade: Contains an Attack Reconnaissance Battalion (AH-64E assets integrated with Troop F MQ-9A Reaper / sUAS teams), an Assault Helicopter Battalion (UH-60M and CH-47F elements), an Assault Helicopter Battalion (Medical), and an Aviation Support Battalion.Brigade Template TypeManeuver BattalionsOrganic ReconnaissanceOrganic Fires & ArtilleryPrimary Vehicle / PlatformMobile BCT (MBCT)3x Mobile Infantry Battalions1x Cavalry Squadron1x Artillery Bn (2x 105mm, 1x 155mm Towed)M1301 Infantry Squad Vehicle (ISV)Stryker BCT (SBCT)3x Stryker Infantry Battalions1x Stryker Cav Sqn + Anti-Tank Troop1x Artillery Bn (3x 155mm M777A2 Towed)Stryker Infantry Carrier Vehicle (8x8)Armored BCT (ABCT)2x Armor-Heavy, 1x Infantry-Heavy CAB1x Armored Cav Sqn (with Tank Troop)1x Artillery Bn (3x 155mm M109A7 Paladin)M1A2 SEPv3 Abrams / M2A3/A4 BradleyCombat Aviation Brigade1x Attack Aviation Bn, 1x Assault Helicopter BnIntegrated sUAS / Troop F AssetsPrecision Air-Delivered Munitions (JAGM/Hellfire)AH-64E / UH-60M / CH-47F AircraftUI/UX Framework & MIL-STD-2525D Symbology Subsystem AnalysisThe user interface implements a three-pane workstation configuration designed for high data density and efficient workspace interaction.┌────────────────────────────────────────────────────────────────────────────────────────┐ +│ Main Military Application Header (Echelon Selector, Doctrinal Mode, Export Tools) │ +├───────────────────────┬────────────────────────────────────────┬───────────────────────┤ +│ Left Panel: │ Central Visual Workspace: │ Right Panel: │ +│ Doctrinal Templates │ Interactive Node-Graph Engine │ Node Inspector │ +│ & Component Palette │ (Panning, Zooming, Drag-and-Drop) │ & Position Editor │ +│ │ │ │ +│ - 2026 MBCT Template │ [Brigade HQ] │ - Unit ID & Name │ +│ - 2026 SBCT Template │ │ │ - Assigned MOS │ +│ - 2026 ABCT Template │ ├── [Infantry Bn] │ - Personnel Search │ +│ - 2026 CAB Template │ │ └── [Rifle Platoon] │ - Weapon Assignment │ +│ - Echelon Blocks │ └── [Artillery Bn] │ - Readiness Status │ +├───────────────────────┴────────────────────────────────────────┴───────────────────────┤ +│ Status Bar (Viewport Scale Factor, Active Node Count, MTOE Validation Status) │ +└────────────────────────────────────────────────────────────────────────────────────────┘ +The workstation layout organizes core workflows into functional zones:Left Panel (Template & Component Palette): Collapsible sidebar containing drag-and-drop building blocks, including complete 2026 brigade templates, battalion/company frameworks, and standalone duty position slots across all branches (Infantry, Medical, Signals, EW, UAV, Supply).Central Visual Workspace: Main interactive area hosting the infinite graph canvas, displaying hierarchical unit lines, command relationships, manning levels, and MIL-STD-2525D tactical map symbols.Right Panel (Node Inspector & Position Editor): Context-sensitive inspector that updates upon selecting a unit or soldier node. It provides editing controls for duty titles, personnel assignments, MOS qualifications, rank requirements, organic equipment allocations, and operational readiness toggles.Third-Party Package & Library Evaluation for MIL-STD-2525 SymbologyRendering standard military symbology in accordance with MIL-STD-2525D/E requires constructing complex 2D vector graphic compositions featuring geometric frames, main function icons (e.g., medical cross, signal lightning bolt, artillery cannon, infantry rifles), status modifiers, and multi-line textual annotations. [ Echelon Modifier: ║║ (Platoon) ] + │ + ┌────────────────┴────────────────┐ + │ ┌─────────────────────────┐ │ + │ │ Friendly Frame (┌┐) │ │ + │ │ │ │ + │ │ Function Icon: + │ │ <── Text Designator: "1/A/1-187 IN (MED)" + │ │ (Medical Cross) │ │ + │ │ │ │ + │ └─────────────────────────┘ │ + └─────────────────────────────────┘ +Evaluating third-party packages, external Javascript libraries, and native C/Rust interop options reveals three distinct implementation strategies for cross-platform Flutter rendering:Integration ApproachTechnical MechanismPlatform SuitabilityPerformance & Memory OverheadArchitectural Trade-Offsmilsymbol.js via JS Interop / QuickJSUses the open-source milsymbol JavaScript library via dart:js_interop on Web, and an embedded QuickJS engine / Headless WebView on Windows and Android.Outstanding native execution on Web; requires embedded JS runtimes on Windows and Android.Low on Web; higher memory footprint and asynchronous string passing latency on native mobile/desktop platforms.Complete MIL-STD-2525D compliance out-of-the-box; introduces external JavaScript execution runtime dependencies on desktop/mobile platforms.Rust Native Core (milsymbol-rs via FFI)Compiles a Rust-based 2525 renderer into native C-shared libraries (.dll for Windows, .so for Android, WebAssembly .wasm for Web) bound via Dart FFI.Uniform high performance across Windows, Android, and Web Assembly.Sub-millisecond rasterization speed; minimal CPU and memory overhead.Maximizes performance and platform consistency (used in native C2 clients like OmniTAK); requires cross-compiling native binaries for target toolchains.Bespoke Native Dart Vector Engine (xml + path_drawing)Parses modular SVG component files directly using pure Dart xml and path_drawing packages into cached native Flutter Path primitives.100% native execution across Windows, Web, and Android without external runtimes.Direct GPU canvas drawing via CustomPainter; zero context-switching overhead.Eliminates third-party engine dependencies; requires building an internal SIDC symbol-code lookup map and bundling SVG asset sets.Selected Symbology ArchitectureTo ensure zero external native binary dependencies while maintaining maximum frame rates on low-power tactical Android tablets and WebAssembly deployments, the system adopts a hybrid vector pipeline:Web Target: Directly interfaces with milsymbol.js via lightweight Dart JS Interop (dart:js_interop) to output inline SVG paths.Native Targets (Windows & Android): Utilizes a native Dart parser that decodes SVG vector paths using path_drawing into immutable Path instances. Symbol components are cached in a thread-safe LRU memory cache indexable by 15-digit Symbol Identification Codes (SIDC).A complete tactical symbol is drawn on the GPU canvas by layering visual primitives:$$\text{Tactical Symbol} = \text{Frame}_{\text{Affiliation}} + \text{Icon}_{\text{Function}} + \text{Modifier}_{\text{Echelon}} + \text{Text}_{\text{Designator}}$$The painter renders a friendly blue frame, places the functional icon (such as medical cross, infantry cross-rifles, or signal lightning bolt), applies echelon modifiers (such as vertical bars for platoons or crosses for battalions), and appends unit text designators alongside.The UI adjusts dynamically across supported hardware targets:Windows Desktop: Displays all three panes concurrently, supporting keyboard navigation (Ctrl+Z undo, Ctrl+F search, Ctrl+D duplicate sub-tree), mouse-wheel pan/zoom, multi-node box selection, and right-click context menus.Web (WASM): Matches the desktop layout while optimizing canvas surface memory and enabling responsive panel toggles for narrower browser windows.Android Tablet/Mobile: Replaces side panels with slide-out bottom sheets and navigation drawers. Touch targets expand to a minimum size of 48x48 dp, and tap-and-hold radial menus replace desktop right-click interactions.Implementation Roadmap, Persistence Architecture, & Performance HardeningSystem implementation follows a five-phase development lifecycle spanning 24 weeks, transitioning from baseline architecture to production platform distribution builds.[Phase 1: Architecture & Data Foundations (Weeks 1-4)] + │ + ▼ +[Phase 2: Canvas Graphics Engine & Gesture Subsystem (Weeks 5-9)] + │ + ▼ +[Phase 3: 2026 Doctrinal Templates & Symbology Engine (Weeks 10-14)] + │ + ▼ +[Phase 4: Persistence, Validation Rules, & Export Engine (Weeks 15-19)] + │ + ▼ +[Phase 5: Platform Optimization, Profiling, & Hardening (Weeks 20-24)] +Phase 1: Architecture & Data Foundations (Weeks 1 – 4): Establish the layered clean architecture codebase, define core Dart domain entities (covering Infantry, Medical, Signal, EW, UAV, Supply, and Engineer positions), construct serialization schemas, and configure continuous integration pipelines for Windows, Web, and Android targets.Phase 2: Canvas Graphics Engine & Gesture Subsystem (Weeks 5 – 9): Build the bespoke CustomPainter rendering layer inside an InteractiveViewer, implement Quadtree spatial indexing, integrate matrix viewport transformations, and construct the cross-platform drag-and-drop state machine.Phase 3: 2026 Doctrinal Templates & Symbology Engine (Weeks 10 – 14): Construct pre-configured template libraries for Mobile BCTs, Stryker BCTs, Armored BCTs, and Combat Aviation Brigades. Implement the hybrid MIL-STD-2525D symbology pipeline.Phase 4: Persistence, Validation Rules, & Export Engine (Weeks 15 – 19): Integrate the Drift transactional database for local storage, construct the real-time MTOE domain validation engine, and develop data export modules supporting JSON, Protobuf, and vector PDF chart rendering.Phase 5: Platform Optimization, Profiling, & Hardening (Weeks 20 – 24): Execute performance profiling using Flutter DevTools, offload heavy graph calculations to background Dart Isolates, isolate visual layers with RepaintBoundary widgets, and assemble release packages (.msi, WASM, .apk).Data persistence utilizes Drift (a type-safe reactive SQLite abstraction layer) on Windows and Android, mapping seamlessly to IndexedDB when running in web environments.Table NamePrimary KeyForeign Key ReferencesStorage Purposeunitsunit_id (UUID)parent_unit_id -> units(unit_id)Stores organizational structure, echelons, and hierarchy links.position_slotsslot_id (UUID)unit_id -> units(unit_id)Stores authorized duty titles, MOS requirements (11B, 68W, 13F, 25H, 17E, 92Y, etc.), and pay grades.personnelsoldier_id (UUID)slot_id -> position_slots(slot_id)Stores soldier profiles, MOS qualifications, and readiness states.templatestemplate_id (UUID)NoneStores serialized JSON structures for 2026 force templates.Performance hardening strategies keep rendering latency below critical limits:Dart Isolates: Layout algorithms (such as Reingold-Tilford tree positioning) and heavy MTOE validation logic run within background Dart Isolates, preventing computational spikes on the main UI thread.Layer Isolation: The canvas separates static elements (grid lines, parent-child link lines) from dynamic elements (active node drag previews) using distinct RepaintBoundary widgets, ensuring that dragging an item only repaints the modified overlay layer.Path Optimization: Vector paths for MIL-STD-2525D symbols are parsed once upon application launch, cached as binary Path objects in memory, and rendered via canvas.drawPath() offset calls, eliminating runtime XML parsing overhead.Operational Extensibility & Architectural AnalysisDeveloping command and control software requires accommodating evolving force structures, varying deployment environments, and network constraints. Analyzing the second- and third-order impacts of key architectural decisions ensures long-term operational viability.[2026 Army Force Structure Updates] + │ + ▼ +[Externalized JSON Template Rules] ──► Decouples doctrine from binary code updates + │ + ▼ +[Offline-First Drift/SQLite Engine] ──► Ensures continuous operation during network loss + │ + ▼ +[Delta Command Synchronizer] ──► Minimizes bandwidth overhead across contested tactical networks +Adapting to Future Doctrinal ReformsThe transition from Infantry BCTs to Mobile BCTs—alongside ongoing modifications to Combat Aviation Brigades—demonstrates how military force designs evolve over time. Hardcoding unit structures directly into UI code would require full application re-compilation and distribution for every doctrinal update.To solve this issue, the platform externalizes force structure definitions into serialized JSON schema files loaded at runtime. When Army force managers modify an MTOE standard (such as adjusting dismount counts within an ISV rifle squad or adding unmanned system operators to a battalion staff), system administrators simply issue an updated JSON definition file. The domain engine parses the new file, updates the template library, and applies the revised validation rules across active task organizations without requiring client binary patches.Gesture Subsystem InteroperabilityEngineers constructing multi-platform drag-and-drop systems must account for differences in input hardware. Desktop mouse interactions offer precise point selection, whereas touch inputs on mobile devices introduce gesture ambiguity, such as distinguishing between panning a graph view and selecting a node for re-parenting.The application resolves input conflicts using an adaptive gesture pipeline. Mouse interactions initiate node drag operations immediately upon exceeding a 2-pixel movement threshold. On touch interfaces, dragging requires a long-press gesture (200ms) accompanied by haptic feedback before unlinking a node from the canvas. This distinction prevents accidental structural changes when users pan across large organizational diagrams on mobile or tablet displays.Offline-First Operation in Contested Network EnvironmentsTactical command posts frequently operate in contested communications environments characterized by bandwidth constraints or intermittent network loss. The application prioritizes an offline-first transactional data model to maintain operational utility under degraded conditions.All user interactions, node re-parenting operations, and personnel assignments write directly to the local transactional database (Drift/SQLite). When network connectivity is degraded or lost, the application continues to operate locally without interruption. When connectivity is restored, a delta synchronization engine transmits queued atomic command events (such as AttachNode or AssignPersonnel) rather than re-transmitting entire organizational models. This event-driven synchronization approach minimizes bandwidth consumption and prevents data conflicts across distributed command elements operating in contested environments. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..460cd9d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,273 @@ +site_name: UTO Manager Documentation +site_description: >- + Flutter-Based Military Unit Task Organization Enterprise System — + U.S. Army 2026 Doctrine Cross-Platform Command & Control Application +site_author: UTO Manager Development Team +site_url: https://git.kellsupport.com/uto_manager/docs + +repo_name: uto_manager +repo_url: https://git.kellsupport.com/uto_manager +edit_uri: edit/develop/docs/ + +copyright: Copyright © 2026 UTO Manager Development Team + +# ----------------------------------------------------------------------------- +# Theme +# ----------------------------------------------------------------------------- +theme: + name: material + language: en + palette: + # Light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: blue + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + accent: blue + toggle: + icon: material/brightness-4 + name: Switch to light mode + font: + text: Roboto + code: Roboto Mono + icon: + repo: fontawesome/brands/git-alt + logo: material/army + features: + - navigation.tabs + - navigation.tabs.sticky + - navigation.sections + - navigation.expand + - navigation.path + - navigation.top + - navigation.footer + - navigation.indexes + - search.highlight + - search.share + - search.suggest + - content.code.copy + - content.code.annotate + - content.tabs.link + - content.tooltips + - toc.follow + +# ----------------------------------------------------------------------------- +# Plugins +# ----------------------------------------------------------------------------- +plugins: + - search: + lang: en + - minify: + minify_html: true + +# ----------------------------------------------------------------------------- +# Markdown Extensions +# ----------------------------------------------------------------------------- +markdown_extensions: + - abbr + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + title: On this page + - tables + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.critic + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: uto_manager + repo: uto_manager + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.snippets: + auto_append: + - docs/includes/abbreviations.md + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + +# ----------------------------------------------------------------------------- +# Extra JavaScript (MathJax for doctrinal formulas) +# ----------------------------------------------------------------------------- +extra_javascript: + - javascripts/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + +# ----------------------------------------------------------------------------- +# Extra CSS +# ----------------------------------------------------------------------------- +extra_css: + - stylesheets/extra.css + +# ----------------------------------------------------------------------------- +# Extra Variables +# ----------------------------------------------------------------------------- +extra: + version: + provider: mike + social: + - icon: fontawesome/brands/git-alt + link: https://git.kellsupport.com/uto_manager + name: Source Repository + analytics: + feedback: + title: Was this page helpful? + ratings: + - icon: material/emoticon-happy-outline + name: This page was helpful + data: 1 + note: Thanks for your feedback! + - icon: material/emoticon-sad-outline + name: This page could be improved + data: 0 + note: Thanks for your feedback! + +# ----------------------------------------------------------------------------- +# Navigation +# ----------------------------------------------------------------------------- +nav: + - Home: index.md + + - User Guide: + - user-guide/index.md + - Getting Started: + - user-guide/getting-started/installation.md + - user-guide/getting-started/quick-start.md + - user-guide/getting-started/interface-overview.md + - Working with Templates: + - user-guide/templates/overview.md + - user-guide/templates/mbct.md + - user-guide/templates/sbct.md + - user-guide/templates/abct.md + - user-guide/templates/cab-heavy.md + - user-guide/templates/cab-light.md + - Canvas & Navigation: + - user-guide/canvas/pan-zoom.md + - user-guide/canvas/node-selection.md + - user-guide/canvas/drag-and-drop.md + - user-guide/canvas/keyboard-shortcuts.md + - Personnel Management: + - user-guide/personnel/assigning-soldiers.md + - user-guide/personnel/mos-reference.md + - user-guide/personnel/readiness-status.md + - Validation & Readiness: + - user-guide/validation/mtoe-validation.md + - user-guide/validation/finding-types.md + - user-guide/validation/resolving-findings.md + - Export & Import: + - user-guide/export/json-export.md + - user-guide/export/pdf-export.md + - user-guide/export/protobuf-export.md + - user-guide/export/import.md + - Platform-Specific Guides: + - user-guide/platforms/windows.md + - user-guide/platforms/web.md + - user-guide/platforms/android.md + + - Developer Guide: + - developer-guide/index.md + - Architecture: + - developer-guide/architecture/overview.md + - developer-guide/architecture/clean-architecture.md + - developer-guide/architecture/state-management.md + - developer-guide/architecture/offline-first.md + - Domain Model: + - developer-guide/domain/entities.md + - developer-guide/domain/enums.md + - developer-guide/domain/repositories.md + - developer-guide/domain/mos-dictionary.md + - Canvas Engine: + - developer-guide/canvas/custom-painter.md + - developer-guide/canvas/viewport-culling.md + - developer-guide/canvas/reingold-tilford.md + - developer-guide/canvas/quadtree.md + - developer-guide/canvas/drag-drop-state-machine.md + - Symbology Engine: + - developer-guide/symbology/mil-std-2525d.md + - developer-guide/symbology/sidc-resolver.md + - developer-guide/symbology/web-pipeline.md + - developer-guide/symbology/native-pipeline.md + - developer-guide/symbology/lru-cache.md + - Database & Persistence: + - developer-guide/database/drift-schema.md + - developer-guide/database/daos.md + - developer-guide/database/migrations.md + - developer-guide/database/indexeddb-web.md + - Validation Engine: + - developer-guide/validation/mtoe-engine.md + - developer-guide/validation/validation-rules.md + - developer-guide/validation/isolate-architecture.md + - Export Engine: + - developer-guide/export/json-codec.md + - developer-guide/export/protobuf-schema.md + - developer-guide/export/pdf-renderer.md + - Performance: + - developer-guide/performance/repaint-boundaries.md + - developer-guide/performance/dart-isolates.md + - developer-guide/performance/benchmarks.md + - CI/CD: + - developer-guide/cicd/pipeline.md + - developer-guide/cicd/build-targets.md + - developer-guide/cicd/code-coverage.md + - Contributing: + - developer-guide/contributing/workflow.md + - developer-guide/contributing/coding-standards.md + - developer-guide/contributing/testing.md + + - Doctrinal Reference: + - doctrinal-reference/index.md + - Force Structures: + - doctrinal-reference/force-structures/mbct.md + - doctrinal-reference/force-structures/sbct.md + - doctrinal-reference/force-structures/abct.md + - doctrinal-reference/force-structures/cab.md + - MOS Reference: + - doctrinal-reference/mos/infantry.md + - doctrinal-reference/mos/medical.md + - doctrinal-reference/mos/field-artillery.md + - doctrinal-reference/mos/signal.md + - doctrinal-reference/mos/cyber-ew.md + - doctrinal-reference/mos/aviation.md + - doctrinal-reference/mos/logistics.md + - doctrinal-reference/mos/engineer.md + - MIL-STD-2525D: + - doctrinal-reference/symbology/overview.md + - doctrinal-reference/symbology/sidc-codes.md + - doctrinal-reference/symbology/affiliation-frames.md + - doctrinal-reference/symbology/echelon-modifiers.md + + - Release Notes: + - release-notes/index.md + - release-notes/v1.0.0.md diff --git a/phased_development_plan.md b/phased_development_plan.md new file mode 100644 index 0000000..6696341 --- /dev/null +++ b/phased_development_plan.md @@ -0,0 +1,842 @@ +# Phased Development Plan + +## Flutter-Based Military Unit Task Organization (UTO) Manager + +### U.S. Army 2026 Doctrine — Cross-Platform Enterprise System + +--- + +## Overview + +This document breaks the master development plan into five structured phases spanning **24 weeks**. Each phase defines concrete deliverables, technical tasks, acceptance criteria, and inter-phase dependencies. The system targets **Windows x64**, **Web (WASM/CanvasKit)**, and **Android** from a single Dart codebase. + +--- + +## Architecture Summary + +```text +[Presentation Layer: CustomPainter / InteractiveViewer / Responsive Shell] + │ + ▼ +[Application State Layer: BLoC / Signals / Super Drag-and-Drop Pipeline] + │ + ▼ +[Domain Layer: MTOE Doctrinal Rules Engine / Structural Validation] + │ + ▼ +[Infrastructure Layer: Drift SQLite / IndexedDB / Protobuf Codecs] +``` + +--- + +## Phase 1: Architecture & Data Foundations + +### Weeks 1 – 4 + +**Objective:** Establish the layered clean architecture codebase, define all core Dart domain entities, construct serialization schemas, and configure CI/CD pipelines for all three target platforms. + +--- + +### 1.1 — Project Scaffolding & Clean Architecture Setup (Week 1) + +**Tasks:** + +- Initialize Flutter project with multi-platform targets: `windows`, `web`, `android` +- Establish clean architecture folder structure: + + ```text + lib/ + ├── domain/ # Entities, value objects, repository interfaces + ├── application/ # BLoC / use cases / state management + ├── infrastructure/ # Drift DB, IndexedDB adapters, Protobuf codecs + └── presentation/ # Widgets, painters, responsive shell + ``` + +- Configure `flutter_lints`, `very_good_analysis`, and project-wide lint rules +- Set up `pubspec.yaml` with initial dependency declarations +- Initialize Git repository with branch protection rules (`main`, `develop`, `feature/*`) + +**Deliverables:** + +- Compilable Flutter project skeleton on all three targets +- Passing `flutter analyze` with zero lint violations +- Git repository with CI trigger configuration + +**Acceptance Criteria:** + +- `flutter run -d windows`, `flutter run -d chrome`, and `flutter run -d android` all launch a blank scaffold without errors + +--- + +### 1.2 — Core Domain Entity Definitions (Weeks 1–2) + +**Tasks:** + +- Define Dart sealed classes and enums for all domain primitives: + - `Echelon` enum: `Brigade`, `Battalion`, `Company`, `Platoon`, `Section`, `Squad`, `Team` + - `DoctrinalBranch` enum: `Infantry`, `Medical`, `Fires`, `Signal`, `CyberEW`, `Aviation`, `Logistics`, `Engineer` + - `AuthorizedRank` enum: `E1`–`E9`, `W1`–`W5`, `O1`–`O10` + - `UnitNode` entity: `unitId (UUID)`, `echelon`, `branch`, `parentUnitId`, `name`, `isKeyLeader` + - `PositionSlot` entity: `slotId (UUID)`, `unitId`, `positionTitle`, `dutyMOS`, `authorizedRank`, `isKeyLeader`, `assignedPersonnelId?` + - `PersonnelRecord` entity: `soldierId (UUID)`, `name`, `primaryMOS`, `payGrade`, `qualifications[]`, `readinessState` + - `DutyMOS` value object with validation against standardized 3-character MOS dictionary +- Define position slot dictionaries for all functional branches: + - **Infantry & Maneuver:** Platoon Leader (11A), Platoon Sergeant (11B/E-7), Squad Leader (11B/E-6), Team Leader (11B/E-5), Automatic Rifleman (11B/E-4), Grenadier (11B/E-4), Rifleman (11B/E-3), sUAS Operator (15W/11B) + - **Medical (CMF 68):** Combat Medic Specialist (68W/E-4), Medical Evacuation NCO (68W/E-6), Treatment NCO (68W/E-6) + - **Field Artillery (CMF 13):** Joint Fire Support Specialist (13F/E-4–E-6), FAATDS Operator (13D/E-4) + - **Signal (CMF 25):** Network Comms Specialist (25H/E-4), Cyber/IT Specialist (25B/E-4) + - **Cyber/EW (CMF 17):** EW Specialist (17E/E-4–E-6) + - **Logistics (CMF 91/92):** Unit Supply Specialist (92Y/E-4), Automated Logistical Specialist (92A/E-4), Vehicle Mechanic (91B/91A/E-4) + - **Engineers (CMF 12):** Combat Engineer (12B/E-4–E-6) +- Implement `UnitRepository` and `PersonnelRepository` abstract interfaces + +**Deliverables:** + +- Complete domain entity library with unit tests +- MOS dictionary data file (JSON) covering all defined specialties +- Repository interface contracts + +**Acceptance Criteria:** + +- 100% unit test coverage on all domain entity validation logic +- MOS validation rejects invalid codes and accepts all defined specialties + +--- + +### 1.3 — Database Schema & Infrastructure Layer (Weeks 2–3) + +**Tasks:** + +- Add `drift` package and configure for Windows/Android (SQLite) and Web (IndexedDB via `drift_web`) +- Define Drift table schemas: + + | Table | Primary Key | Foreign Keys | Purpose | + |---|---|---|---| + | `units` | `unit_id (UUID)` | `parent_unit_id → units(unit_id)` | Organizational hierarchy | + | `position_slots` | `slot_id (UUID)` | `unit_id → units(unit_id)` | Authorized duty positions | + | `personnel` | `soldier_id (UUID)` | `slot_id → position_slots(slot_id)` | Soldier profiles & readiness | + | `templates` | `template_id (UUID)` | None | Serialized 2026 force templates | + +- Implement Drift DAOs for CRUD operations on all four tables +- Configure database migrations framework (versioned migration files) +- Implement `JsonTemplateCodec` for serializing/deserializing unit tree structures +- Stub Protobuf schema definitions for future export pipeline (Phase 4) + +**Deliverables:** + +- Fully functional Drift database with all four tables +- DAO implementations with integration tests against in-memory SQLite +- JSON codec for unit tree serialization + +**Acceptance Criteria:** + +- Integration tests pass: create, read, update, delete operations on all tables +- Database migrations run cleanly from version 1 → current +- JSON round-trip serialization produces identical domain objects + +--- + +### 1.4 — CI/CD Pipeline Configuration (Week 4) + +**Tasks:** + +- Configure GitHub Actions (or equivalent) with three build matrix targets: + - `flutter build windows` + - `flutter build web --wasm` + - `flutter build apk` +- Add automated test stages: `flutter test`, `flutter analyze` +- Configure artifact upload for build outputs (`.exe`, `web/`, `.apk`) +- Set up code coverage reporting (minimum 80% threshold gate) + +**Deliverables:** + +- Passing CI pipeline on all three platform targets +- Automated test and lint gates on pull requests +- Build artifact storage configured + +**Acceptance Criteria:** + +- All three platform builds succeed in CI without manual intervention +- Pull requests blocked on failing tests or lint violations + +--- + +### Phase 1 Exit Criteria + +- [ ] Clean architecture folder structure established and enforced by linting +- [ ] All domain entities defined with full unit test coverage +- [ ] Drift database operational on Windows, Web, and Android +- [ ] CI/CD pipeline passing on all three platform targets +- [ ] MOS dictionary data file complete for all functional branches + +--- + +## Phase 2: Canvas Graphics Engine & Gesture Subsystem + +### Weeks 5 – 9 + +**Objective:** Build the bespoke `CustomPainter` rendering layer, implement Quadtree spatial indexing, integrate matrix viewport transformations, and construct the cross-platform drag-and-drop state machine. + +--- + +### 2.1 — CustomPainter Canvas Engine Foundation (Weeks 5–6) + +**Tasks:** + +- Implement `UtoCanvasPainter extends CustomPainter` with: + - `paint(Canvas canvas, Size size)` rendering loop + - `shouldRepaint()` optimized to dirty-flag comparison (not full equality) + - Node rendering via `canvas.drawRect()`, `canvas.drawPath()`, `canvas.drawParagraph()` + - Parent-child connection line rendering via `canvas.drawLine()` / `canvas.drawPath()` +- Wrap painter inside `InteractiveViewer` with: + - Configurable `minScale` / `maxScale` bounds + - `TransformationController` exposing the 4×4 viewport matrix `M` +- Implement viewport culling using inverse matrix transform: + + ```text + Viewport_visible = M⁻¹ × S + ``` + + - Skip rendering nodes/lines outside the calculated visible bounding box + - Benchmark: maintain 60 FPS at 5,000+ nodes on Windows, 2,000+ on Web, 1,500+ on Android +- Implement `NodeRenderModel` — a flat list of pre-computed render primitives consumed by the painter (decoupled from domain entities) + +**Deliverables:** + +- Functional canvas painter rendering placeholder node boxes and connection lines +- Viewport culling active and measurable via Flutter DevTools frame timeline +- `NodeRenderModel` data structure defined + +**Acceptance Criteria:** + +- 60 FPS maintained with 500 placeholder nodes on all three platforms +- Viewport culling demonstrably skips off-screen nodes (verified via paint call counters) + +--- + +### 2.2 — Reingold-Tilford Tree Layout Algorithm (Week 6) + +**Tasks:** + +- Implement the adapted Reingold-Tilford hierarchical tree layout algorithm in a dedicated `layout/` module: + - Calculate subtree widths bottom-up for all echelon levels + - Assign `(x, y)` canvas coordinates to each node based on subtree width and echelon depth + - Enforce horizontal separation across functional branches (Maneuver, Fires, Recon, Engineer, Sustainment) + - Enforce vertical alignment across echelons (Brigade → Battalion → Company → Platoon → Squad → Team → Individual) +- Offload layout computation to a **Dart Isolate** to prevent UI thread blocking +- Implement `LayoutResult` message passing between isolate and main thread +- Trigger layout recalculation on: node add, node remove, node re-parent, template load + +**Deliverables:** + +- Reingold-Tilford layout engine producing correct `(x, y)` coordinates for arbitrary unit trees +- Isolate-based async layout computation +- Layout recalculation triggered correctly on all structural change events + +**Acceptance Criteria:** + +- Layout algorithm correctly positions a full Brigade Combat Team (500+ nodes) without visual overlap +- Layout computation completes in < 100ms for a full BCT on Windows +- UI thread remains unblocked during layout recalculation (verified via DevTools) + +--- + +### 2.3 — Quadtree Spatial Index (Week 7) + +**Tasks:** + +- Implement a `Quadtree` spatial index in pure Dart: + - Insert node bounding boxes on layout completion + - Query nearest-neighbor candidates within a configurable proximity radius + - Update index on node position changes (drag operations) + - Remove entries on node deletion +- Integrate Quadtree with the canvas hit-testing pipeline: + - Map screen-space tap/click coordinates through `M⁻¹` to canvas space + - Query Quadtree for the node at the transformed coordinate + - Return `null` for taps on empty canvas space + +**Deliverables:** + +- Pure Dart Quadtree implementation with unit tests +- Hit-testing pipeline correctly identifying nodes from screen-space coordinates + +**Acceptance Criteria:** + +- Quadtree hit-testing correctly identifies nodes in a 1,000-node tree with < 1ms query time +- No false positives or missed hits in unit tests covering edge cases (overlapping bounds, boundary nodes) + +--- + +### 2.4 — Cross-Platform Drag-and-Drop State Machine (Weeks 7–9) + +**Tasks:** + +- Implement the drag-and-drop event state machine with four deterministic states: + 1. **`Idle`** — No active drag; canvas responds to pan/zoom gestures + 2. **`DragInitiated`** — Node selected; subordinate subtree isolated into overlay render layer; drag payload captured + 3. **`DragInProgress`** — Dragged node moves across canvas; Quadtree proximity queries identify candidate parent nodes; doctrinal validation highlights valid (green) / invalid (red) drop targets + 4. **`DropExecuted`** — Re-parenting command issued; relational keys updated in local store; Reingold-Tilford layout recalculated; painter notified via `shouldRepaint` +- Implement platform-adaptive gesture thresholds: + - **Desktop (mouse):** Drag initiates after 2-pixel movement threshold + - **Mobile/Tablet (touch):** Drag requires 200ms long-press + haptic feedback before node unlinks +- Integrate `super_drag_and_drop` package for cross-component drag payload integrity +- Implement `DragOverlayPainter` as a separate `RepaintBoundary` layer above the main canvas (prevents full canvas repaint during drag) +- Implement `AttachNodeCommand` and `DetachNodeCommand` as undoable command objects + +**Deliverables:** + +- Fully functional drag-and-drop re-parenting on Windows (mouse) and Android (touch) +- Visual feedback: green highlight for valid drop targets, red for invalid +- Undo/redo stack for node re-parenting operations +- Drag overlay rendered in isolated `RepaintBoundary` layer + +**Acceptance Criteria:** + +- Dragging a Rifle Squad to an Infantry Platoon shows green highlight and completes re-parenting +- Dragging a Fire Team directly to a Brigade HQ shows red invalid indicator +- Long-press threshold (200ms) correctly prevents accidental drags on touch devices +- Undo (Ctrl+Z / gesture) correctly reverses re-parenting operations +- Drag overlay does not trigger full canvas repaint (verified via DevTools) + +--- + +### Phase 2 Exit Criteria + +- [ ] CustomPainter canvas engine rendering nodes and connection lines with viewport culling +- [ ] Reingold-Tilford layout algorithm operational in background Dart Isolate +- [ ] Quadtree spatial index integrated with hit-testing pipeline +- [ ] Cross-platform drag-and-drop state machine functional on Windows and Android +- [ ] 60 FPS maintained at target node counts on all three platforms + +--- + +## Phase 3: 2026 Doctrinal Templates & Symbology Engine + +### Weeks 10 – 14 + +**Objective:** Construct pre-configured 2026 doctrinal template libraries for all four BCT types and implement the hybrid MIL-STD-2525D symbology rendering pipeline. + +--- + +### 3.1 — Doctrinal Template Library (Weeks 10–12) + +**Tasks:** + +- Implement JSON-driven template loader that parses externalized force structure definition files at runtime (no hardcoded unit structures in binary) +- Build complete 2026 doctrinal templates as JSON schema files: + + **Mobile Brigade Combat Team (MBCT):** + + - 3× Mobile Infantry Battalions (each with HHC, 3× Rifle Companies, Weapons Company) + - Rifle Company: 3× Rifle Platoons + Weapons Platoon + - Rifle Platoon: HQ (PL 11A/O-2, PSG 11B/E-7, RTO 25H/E-3, Medic 68W/E-4, FSO 13F/E-6) + 3× Rifle Squads + Weapons Section + - Rifle Squad (SaaS): SL (11B/E-6), 2× TL (11B/E-5), 2× Auto Rifleman XM250 (11B/E-4), 2× Grenadier XM7+M320 (11B/E-4), 1× Rifleman/sUAS Operator (15W/11B/E-4), 1× Rifleman (11B/E-3) + - 1× Cavalry Squadron (HHT + 3× Cav Troops + Anti-Tank Troop) + - 1× Field Artillery Battalion (2× 105mm batteries + 1× 155mm towed battery) + - Multi-Domain Effects Platoon (MDEP): EW (17E), C-sUAS, EMSO + - Hunter-Killer Platoon (HKP): sUAS + precision targeting assets + - Brigade Engineer Battalion + - Brigade Support Battalion + + **Stryker Brigade Combat Team (SBCT):** + + - 3× Stryker Infantry Battalions (HHC with organic medical 68W, signal 25H, sniper sections) + - Cavalry Reconnaissance Squadron (HHT + 3× Stryker Cav Troops + Anti-Tank Troop with 9× Stryker ATGM) + - Field Artillery Battalion (3× batteries, 24× M777A2 155mm towed howitzers) + - Brigade Engineer Battalion (signal 25H, MI, combat engineer 12B companies) + - Brigade Support Battalion (medical, distribution, maintenance) + + **Armored Brigade Combat Team (ABCT):** + + - 2× Armor-Heavy CABs: HHC + 2× Tank Companies (14× M1A2 SEPv3 each) + 1× Mech Infantry Company (14× M2A3/A4 Bradley) + - 1× Infantry-Heavy CAB + - HHC elements: Battalion Medical Platoon (68W), Mechanic Sections (91A/91B), Scout Platoons + - Armored Cavalry Squadron (HHT + 3× Armored Cav Troops + 1× Tank Troop with 14× M1A2) + - Field Artillery Battalion (3× batteries, 18× M109A7 Paladin 155mm SPH) + - Brigade Engineer Battalion (Sapper platoons 12B organic to each CAB) + + **Combat Aviation Brigade (CAB) — Heavy:** + + - Attack Aviation Battalion (24× AH-64E Apache, pilots 153A, crew chiefs 15T) + - Assault Helicopter Battalion (30× UH-60M Black Hawk + 12× CH-47F Chinook) + - Air Ambulance Company (15× HH-60M, 68W flight medics + 153A aviators) + - Aviation Support Battalion (intermediate maintenance 15B/15D/15G, supply 92Y) + + **Combat Aviation Brigade (CAB) — Light:** + + - Attack Reconnaissance Battalion (AH-64E + Troop F MQ-9A/sUAS) + - Assault Helicopter Battalion (UH-60M + CH-47F) + - Assault Helicopter Battalion (Medical) + - Aviation Support Battalion + +- Implement `TemplateInstantiator` service that converts a JSON template into a full `UnitNode` tree and persists it to the Drift database in a single transaction +- Implement runtime template update mechanism: updated JSON files reload without binary recompilation + +**Deliverables:** + +- JSON template files for all five BCT configurations (MBCT, SBCT, ABCT, CAB-Heavy, CAB-Light) +- `TemplateInstantiator` service with integration tests +- Runtime template reload mechanism + +**Acceptance Criteria:** + +- Instantiating an MBCT template creates the correct number of units, position slots, and personnel records in the database +- Template instantiation completes in < 2 seconds for a full BCT +- Updated JSON template files reload correctly without app restart + +--- + +### 3.2 — MIL-STD-2525D Symbology Engine (Weeks 12–14) + +**Tasks:** + +- Implement hybrid symbology pipeline: + + **Web Target (milsymbol.js via JS Interop):** + + - Integrate `milsymbol.js` via `dart:js_interop` + - Pass 15-digit Symbol Identification Codes (SIDC) to JS library + - Receive inline SVG path data and render via `canvas.drawPath()` + + **Native Targets (Windows & Android — Pure Dart SVG Parser):** + + - Bundle modular SVG component asset files for all required symbol elements: + - Affiliation frames (Friendly blue, Hostile red, Neutral green, Unknown yellow) + - Function icons: infantry cross-rifles, medical cross, signal lightning bolt, artillery cannon, engineer castle, aviation rotor, EW lightning, UAV silhouette, logistics wheel + - Echelon modifiers: Team (•), Squad (••), Section (•••), Platoon (|), Company (||), Battalion (|||), Brigade (X), Division (XX) + - Parse SVG paths using `path_drawing` package into immutable `Path` objects at app launch + - Cache parsed `Path` objects in thread-safe LRU cache indexed by SIDC + - Render tactical symbols by layering primitives: + + ```text + Tactical Symbol = Frame_Affiliation + Icon_Function + Modifier_Echelon + Text_Designator + ``` + +- Implement `SidcResolver` that maps `(DoctrinalBranch, Echelon, Affiliation)` tuples to 15-digit SIDC codes +- Implement `TacticalSymbolPainter` that draws complete MIL-STD-2525D symbols on the GPU canvas +- Integrate symbol rendering into the main `UtoCanvasPainter` node rendering loop + +**Deliverables:** + +- Functional MIL-STD-2525D symbol rendering on all three platforms +- LRU symbol cache with configurable capacity +- `SidcResolver` mapping all defined branches and echelons to valid SIDC codes +- SVG asset bundle for all required symbol components + +**Acceptance Criteria:** + +- All defined branch/echelon combinations render correct MIL-STD-2525D symbols +- Symbol cache hit rate > 95% during normal canvas rendering (verified via cache metrics) +- Symbol rendering adds < 2ms overhead per frame on Android (verified via DevTools) +- Web target renders symbols via milsymbol.js without visible quality difference from native + +--- + +### 3.3 — Three-Pane UI Shell (Weeks 13–14) + +**Tasks:** + +- Implement responsive three-pane workstation layout: + + **Windows / Web Desktop:** + + ```text + ┌─────────────────────────────────────────────────────────────────────┐ + │ Header: Echelon Selector | Doctrinal Mode | Export Tools │ + ├──────────────────┬──────────────────────────────┬───────────────────┤ + │ Left Panel: │ Central Canvas Workspace │ Right Panel: │ + │ Template Palette │ (Pan / Zoom / Drag-and-Drop) │ Node Inspector │ + ├──────────────────┴──────────────────────────────┴───────────────────┤ + │ Status Bar: Scale Factor | Active Node Count | MTOE Validation │ + └─────────────────────────────────────────────────────────────────────┘ + ``` + + - Left panel: collapsible sidebar with template drag sources (MBCT, SBCT, ABCT, CAB, echelon blocks, individual duty slots) + - Right panel: context-sensitive inspector updating on node selection (unit ID, MOS, personnel search, weapon assignment, readiness status) + - Keyboard shortcuts: `Ctrl+Z` undo, `Ctrl+Y` redo, `Ctrl+F` search, `Ctrl+D` duplicate subtree, `Ctrl+S` save + - Mouse-wheel pan/zoom, multi-node box selection, right-click context menus + + **Android Tablet/Mobile:** + + - Replace left panel with navigation drawer (slide-out) + - Replace right panel with bottom sheet inspector (slide-up) + - Minimum touch target size: 48×48 dp + - Tap-and-hold radial menus replace right-click context menus + - Haptic feedback on drag initiation + +**Deliverables:** + +- Responsive three-pane layout functional on Windows and Web +- Adaptive mobile layout with drawer and bottom sheet on Android +- All keyboard shortcuts implemented on desktop +- Touch-optimized gesture targets on Android + +**Acceptance Criteria:** + +- Three-pane layout renders correctly at 1920×1080 and 2560×1440 on Windows +- Mobile layout correctly switches to drawer/bottom-sheet at Android tablet and phone breakpoints +- All keyboard shortcuts function correctly on Windows and Web +- Touch targets meet 48×48 dp minimum on Android + +--- + +### Phase 3 Exit Criteria + +- [ ] All five BCT doctrinal templates (MBCT, SBCT, ABCT, CAB-Heavy, CAB-Light) instantiable from JSON +- [ ] MIL-STD-2525D symbology rendering on all three platforms +- [ ] Three-pane UI shell functional on desktop and adaptive on Android +- [ ] Runtime template reload mechanism operational + +--- + +## Phase 4: Persistence, Validation Rules, & Export Engine + +### Weeks 15 – 19 + +**Objective:** Integrate the full Drift transactional database, construct the real-time MTOE domain validation engine, implement offline-first delta synchronization, and develop data export modules. + +--- + +### 4.1 — Full Persistence Integration & Offline-First Architecture (Weeks 15–16) + +**Tasks:** + +- Complete Drift repository implementations for all four tables (units, position_slots, personnel, templates) +- Implement reactive streams: Drift `watchAll()` queries feeding BLoC state streams +- Implement `CommandEventStore` for offline-first operation: + - All structural changes (node re-parent, personnel assign, slot modify) write as atomic `CommandEvent` records + - Events queue locally when network is unavailable + - `DeltaSynchronizer` transmits queued events on connectivity restoration + - Event types: `AttachNodeEvent`, `DetachNodeEvent`, `AssignPersonnelEvent`, `UnassignPersonnelEvent`, `ModifySlotEvent` +- Implement conflict resolution strategy for concurrent edits (last-write-wins with timestamp, flagging conflicts for manual review) +- Configure `drift_web` for IndexedDB persistence on Web target +- Implement database backup/restore functionality (export to encrypted JSON archive) + +**Deliverables:** + +- Full reactive persistence layer with Drift streams feeding UI state +- `CommandEventStore` with offline queue and delta synchronizer +- Conflict resolution mechanism +- Database backup/restore functionality + +**Acceptance Criteria:** + +- Application continues full operation with zero network connectivity (offline-first verified) +- Delta synchronizer transmits only changed events (not full model) on reconnection +- Reactive streams update UI within 16ms of database write (one frame budget) +- Backup/restore round-trip produces identical database state + +--- + +### 4.2 — Real-Time MTOE Domain Validation Engine (Weeks 16–18) + +**Tasks:** + +- Implement `MtoeValidationEngine` running in a background Dart Isolate: + - **MOS Mismatch Detection:** Flag when assigned soldier's primary MOS ≠ slot's authorized duty MOS + - **Rank Mismatch Detection:** Flag when assigned soldier's pay grade ≠ slot's authorized rank + - **Vacant Leadership Slot Detection:** Flag unfilled Key Leader positions (Squad Leader, Platoon Leader, Platoon Sergeant, Company Commander, etc.) + - **Missing Critical Support Role Detection:** Flag maneuver platoons lacking attached 68W Combat Medic or 13F Fire Support Specialist + - **Structural Hierarchy Violation Detection:** Flag invalid parent-child echelon relationships (e.g., Squad directly under Brigade) + - **Doctrinal Strength Deviation:** Flag units with manning levels below 70% of authorized strength +- Implement validation result model: `ValidationFinding(severity, unitId, slotId, findingCode, description)` +- Severity levels: `Critical` (red), `Warning` (amber), `Advisory` (blue) +- Integrate validation findings into: + - Status bar (aggregate finding counts by severity) + - Node visual indicators (colored border/badge on nodes with findings) + - Right panel inspector (detailed finding list for selected node) +- Implement drag-and-drop pre-validation: evaluate proposed re-parenting before drop execution + +**Deliverables:** + +- `MtoeValidationEngine` with all defined validation rules +- Real-time validation findings displayed in status bar, node indicators, and inspector panel +- Pre-validation during drag-and-drop operations +- Validation engine running in background Isolate (no UI thread impact) + +**Acceptance Criteria:** + +- All defined validation rules correctly identify violations in test unit trees +- Validation engine processes a full BCT (500+ nodes) in < 500ms in background Isolate +- Node visual indicators update within one frame of validation completion +- Dragging a Fire Team to Brigade HQ shows red pre-validation indicator before drop + +--- + +### 4.3 — Data Export Engine (Weeks 18–19) + +**Tasks:** + +- Implement **JSON Export:** Full unit tree serialization to structured JSON (human-readable, importable) +- Implement **Protobuf Export:** Binary-encoded unit tree using pre-defined `.proto` schema (compact, network-efficient) +- Implement **Vector PDF Chart Export:** + - Render the full organizational chart to a PDF document using `pdf` package + - Preserve MIL-STD-2525D symbols as vector paths in PDF output + - Support configurable page sizes (Letter, A4, Tabloid/A3 for large formations) + - Include cover page with unit designation, date, classification marking placeholder +- Implement **Import Pipeline:** JSON import with validation against current doctrinal rules +- Implement export UI: export dialog with format selection, scope selection (full tree / selected subtree), and file save dialog + +**Deliverables:** + +- JSON, Protobuf, and vector PDF export modules +- JSON import pipeline with validation +- Export UI dialog integrated into application header + +**Acceptance Criteria:** + +- JSON export/import round-trip produces identical unit tree (verified by deep equality test) +- Protobuf export file size < 50% of equivalent JSON for a full BCT +- PDF export renders all MIL-STD-2525D symbols as vector paths (not rasterized) +- PDF export completes in < 10 seconds for a full BCT on Windows + +--- + +### Phase 4 Exit Criteria + +- [ ] Full reactive Drift persistence layer operational on all three platforms +- [ ] Offline-first operation verified with delta synchronization +- [ ] MTOE validation engine detecting all defined violation types in real time +- [ ] JSON, Protobuf, and vector PDF export modules functional +- [ ] JSON import pipeline with doctrinal validation + +--- + +## Phase 5: Platform Optimization, Profiling, & Hardening + +### Weeks 20 – 24 + +**Objective:** Execute comprehensive performance profiling, apply rendering optimizations, harden the application for production deployment, and assemble release packages for all three platforms. + +--- + +### 5.1 — Performance Profiling & Rendering Optimization (Weeks 20–21) + +**Tasks:** + +- Profile all three platform targets using Flutter DevTools: + - Frame timeline analysis: identify jank frames (> 16ms) and their root causes + - Memory profiler: identify heap growth patterns and object retention issues + - CPU profiler: identify hot paths in layout, painting, and validation logic +- Apply `RepaintBoundary` isolation strategy: + - Static layer: grid lines, parent-child connection lines (repaints only on zoom/pan) + - Dynamic layer: active drag preview overlay (repaints only during drag) + - Node layer: individual unit nodes (repaints only on state change) +- Optimize Reingold-Tilford layout: cache subtree width calculations, skip unchanged subtrees +- Optimize Quadtree: implement bulk-insert for template instantiation, lazy rebuild on large structural changes +- Optimize symbol cache: tune LRU capacity per platform (Windows: 2,000 entries, Android: 500 entries, Web: 1,000 entries) +- Implement progressive loading for large templates: render visible viewport nodes first, load off-screen nodes asynchronously + +**Performance Targets:** + +| Platform | Node Count | Target FPS | Max Frame Time | +|---|---|---|---| +| Windows x64 | 5,000+ | 60 FPS | 16ms | +| Web (WASM) | 2,000+ | 60 FPS | 16ms | +| Android | 1,500+ | 60 FPS | 16ms | + +**Deliverables:** + +- DevTools profiling reports for all three platforms +- Applied `RepaintBoundary` isolation across all canvas layers +- Performance benchmark suite (automated frame rate tests at target node counts) + +**Acceptance Criteria:** + +- All three platforms meet target FPS at specified node counts (verified by automated benchmarks) +- No memory leaks detected over 30-minute continuous operation sessions +- Dart Isolate offloading verified: main thread frame time < 8ms during layout recalculation + +--- + +### 5.2 — Heavy Computation Isolate Offloading (Week 21) + +**Tasks:** + +- Audit all computationally intensive operations and confirm Isolate offloading: + - Reingold-Tilford layout computation → background Isolate ✓ (Phase 2) + - MTOE validation engine → background Isolate ✓ (Phase 4) + - JSON/Protobuf serialization for large exports → background Isolate + - PDF rendering for large formations → background Isolate +- Implement `IsolatePool` for managing multiple concurrent background computations +- Implement progress reporting from Isolates to UI (progress indicators for long operations) +- Implement Isolate cancellation for superseded layout requests (cancel in-flight layout when new structural change arrives) + +**Deliverables:** + +- All heavy computations confirmed offloaded to background Isolates +- `IsolatePool` managing concurrent background tasks +- Progress indicators for long-running operations (export, large template instantiation) + +**Acceptance Criteria:** + +- Main UI thread frame time remains < 8ms during any background computation +- Isolate cancellation correctly aborts superseded layout requests +- Progress indicators display for all operations > 500ms + +--- + +### 5.3 — Platform-Specific Hardening (Weeks 22–23) + +**Tasks:** + +**Windows x64:** + +- Implement multi-window support (open multiple UTO workspaces simultaneously) +- Implement high-DPI scaling (verify at 100%, 125%, 150%, 200% display scaling) +- Implement system tray integration and window state persistence (size, position, panel widths) +- Configure `.msi` installer with proper registry entries and uninstall support +- Implement Windows file association for `.uto` project files + +**Web (WASM/CanvasKit):** + +- Optimize WASM bundle size (tree-shaking, deferred loading of template assets) +- Implement IndexedDB storage quota management (warn user when approaching browser storage limits) +- Implement memory-bounded canvas surface allocation (prevent OOM on low-memory browser tabs) +- Configure service worker for offline PWA capability +- Test across Chrome, Edge, and Firefox + +**Android:** + +- Implement battery profiling: reduce background Isolate activity when battery < 20% +- Verify touch target sizes meet 48×48 dp minimum across all interactive elements +- Implement Android back-gesture handling for panel navigation +- Configure `.aab` release build with ProGuard/R8 optimization +- Test on Android 12, 13, and 14 across tablet and phone form factors + +**Deliverables:** + +- Windows `.msi` installer with file association +- Web PWA with offline capability and storage quota management +- Android `.aab` release build optimized for tablet and phone + +**Acceptance Criteria:** + +- Windows installer installs/uninstalls cleanly; `.uto` file association opens correct workspace +- Web app functions offline after initial load (PWA service worker active) +- Android app passes battery profiling: no excessive background drain +- All touch targets verified ≥ 48×48 dp on Android + +--- + +### 5.4 — Security, Accessibility, & Final QA (Weeks 23–24) + +**Tasks:** + +- Implement classification marking placeholder system (UNCLASSIFIED / FOR OFFICIAL USE ONLY banners) +- Implement data-at-rest encryption for local Drift database (SQLCipher integration) +- Conduct accessibility audit: + - Screen reader compatibility (Windows Narrator, Android TalkBack) + - Minimum contrast ratios for all text elements (WCAG 2.1 AA) + - Keyboard-only navigation completeness on Windows/Web +- Execute end-to-end test suite covering all critical user workflows: + - Template instantiation → drag-and-drop re-parenting → personnel assignment → export + - Offline operation → reconnection → delta synchronization + - Validation finding detection → resolution → re-validation +- Conduct load testing: instantiate 10 simultaneous full BCT templates, verify stability + +**Deliverables:** + +- SQLCipher database encryption integrated +- Accessibility audit report with all critical issues resolved +- End-to-end test suite passing on all three platforms +- Load test results documented + +**Acceptance Criteria:** + +- Database encryption verified: raw SQLite file is unreadable without key +- All WCAG 2.1 AA contrast requirements met +- End-to-end test suite passes with 100% success rate on all three platforms +- Load test: 10 simultaneous BCT templates stable for 10 minutes without crash or memory leak + +--- + +### 5.5 — Release Package Assembly (Week 24) + +**Tasks:** + +- Assemble Windows release: signed `.msi` installer + portable `.exe` archive +- Assemble Web release: optimized WASM bundle + static hosting configuration +- Assemble Android release: signed `.aab` for Google Play + sideload `.apk` +- Generate release notes documenting all features, known limitations, and upgrade instructions +- Tag release in version control (`v1.0.0`) +- Archive build artifacts with SHA-256 checksums + +**Deliverables:** + +- Signed Windows `.msi` installer +- Optimized Web WASM bundle +- Signed Android `.aab` and `.apk` +- Release notes and SHA-256 checksums + +**Acceptance Criteria:** + +- All three release packages install and launch correctly on clean target systems +- SHA-256 checksums verified for all artifacts +- Release tagged in version control + +--- + +### Phase 5 Exit Criteria + +- [ ] All three platforms meet FPS targets at specified node counts +- [ ] All heavy computations confirmed offloaded to background Isolates +- [ ] Platform-specific hardening complete (Windows multi-window, Web PWA, Android battery profiling) +- [ ] Database encryption integrated +- [ ] End-to-end test suite passing on all three platforms +- [ ] Release packages assembled and signed for all three platforms + +--- + +## Inter-Phase Dependency Map + +```text +Phase 1 (Architecture & Data) + │ + ├──► Phase 2 (Canvas Engine) [Requires: Domain entities, DB schema] + │ │ + │ └──► Phase 3 (Templates & Symbology) [Requires: Canvas engine, Layout algorithm] + │ │ + │ └──► Phase 4 (Persistence & Validation) [Requires: Templates, Full DB] + │ │ + │ └──► Phase 5 (Optimization & Release) [Requires: All prior phases] + │ + └──► Phase 3 (partial: JSON template schema) [Requires: Domain entities only] +``` + +--- + +## Technology Stack Summary + +| Layer | Technology | Rationale | +|---|---|---| +| UI Framework | Flutter (Dart) | Single codebase for Windows, Web, Android | +| Rendering Engine | CustomPainter + InteractiveViewer | GPU-direct drawing; bypasses widget tree overhead | +| State Management | BLoC + Signals | Reactive atomic state; prevents full widget tree rebuilds | +| Drag-and-Drop | super_drag_and_drop | Cross-platform payload integrity | +| Local Database | Drift (SQLite / IndexedDB) | Type-safe reactive ORM; offline-first | +| Encryption | SQLCipher | Data-at-rest protection | +| Symbology (Web) | milsymbol.js via dart:js_interop | Full MIL-STD-2525D compliance on Web | +| Symbology (Native) | path_drawing + SVG assets + LRU cache | Zero external runtime dependencies on Windows/Android | +| Background Compute | Dart Isolates | Offload layout, validation, export from UI thread | +| Serialization | JSON + Protobuf | Human-readable + compact binary export formats | +| PDF Export | pdf package | Vector-quality organizational chart output | +| CI/CD | GitHub Actions | Automated multi-platform build and test matrix | + +--- + +## Risk Register + +| Risk | Probability | Impact | Mitigation | +|---|---|---|---| +| WASM performance below 2,000-node target | Medium | High | Early benchmark in Phase 2; apply aggressive culling and canvas surface limits | +| milsymbol.js JS Interop latency on Web | Low | Medium | Cache SVG output; pre-render symbols at app load | +| Drift IndexedDB storage quota exceeded on Web | Medium | Medium | Implement quota monitoring and user warnings in Phase 5 | +| Reingold-Tilford layout time exceeds 100ms for large BCTs | Low | Medium | Incremental layout: only recalculate affected subtrees | +| Android touch gesture ambiguity (pan vs. drag) | Medium | High | 200ms long-press threshold + haptic feedback (Phase 2); user testing in Phase 5 | +| Army doctrinal template changes post-release | High | Low | Externalized JSON templates; runtime reload without binary update | +| SQLCipher key management complexity | Low | High | Use platform keychain (Windows Credential Manager, Android Keystore) for key storage | + +--- + +Document Version: 1.0 | Generated: 2026-08-07 | Based on: master_development_plan.md