chore: initial project setup — git, README, .gitignore, MkDocs, VSCode
This commit is contained in:
UTO Manager Dev
commit
ee72edacb0
|
|
@ -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
|
||||||
|
|
@ -0,0 +1,5 @@
|
||||||
|
{
|
||||||
|
"default": true,
|
||||||
|
"MD013": false,
|
||||||
|
"MD060": false
|
||||||
|
}
|
||||||
|
|
@ -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"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
@ -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/"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
@ -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
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,286 @@
|
||||||
|
# UTO Manager
|
||||||
|
|
||||||
|
## Flutter-Based Military Unit Task Organization Enterprise System
|
||||||
|
|
||||||
|
### U.S. Army 2026 Doctrine — Cross-Platform Command & Control Application
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
[](https://flutter.dev)
|
||||||
|
[](https://dart.dev)
|
||||||
|
[](https://flutter.dev/multi-platform)
|
||||||
|
[](LICENSE)
|
||||||
|
[](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
|
||||||
|
|
@ -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<NodeId>` 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.
|
||||||
|
|
@ -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)
|
||||||
|
|
@ -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
|
||||||
|
```
|
||||||
|
|
@ -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 |
|
||||||
|
|
@ -0,0 +1,34 @@
|
||||||
|
<!-- Abbreviations for MkDocs snippets auto-append -->
|
||||||
|
<!-- These definitions provide hover tooltips throughout the documentation -->
|
||||||
|
|
||||||
|
*[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
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
<div class="grid cards" markdown>
|
||||||
|
|
||||||
|
- :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)
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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)
|
||||||
|
|
@ -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();
|
||||||
|
});
|
||||||
|
|
@ -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 |
|
||||||
|
|
@ -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.*
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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;
|
||||||
|
}
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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% |
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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.
|
||||||
File diff suppressed because one or more lines are too long
|
|
@ -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
|
||||||
|
|
@ -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<NodeId>` 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
|
||||||
Loading…
Reference in New Issue