43 KiB

Raw Blame History

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

[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 ✅ COMPLETE (2026-08-07)

Status: All Phase 1 deliverables completed and merged to main. 94/94 tests passing. flutter analyze — No issues found. Branch: feature/phase-1-foundations → merged 2026-08-07.

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:

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:
```
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 ✅ COMPLETE (2026-08-09)

Status: Phase 3 template library and import/export deliverables completed and merged to main. 191/191 tests passing. flutter analyze — No issues found. Branch: feature/phase-3-templates-validation-export → merged 2026-08-09.

Completed in this phase:

DoctrinalTemplates — all five 2026 BCT templates (MBCT, SBCT, ABCT, CAB-Heavy, CAB-Light)

TemplateInstantiator — converts UnitDefinition trees to live domain objects

MtoeValidationEngine — 7 validation rules (V001–V007) covering MOS/rank mismatch, vacant key leaders, missing medic/FSO, hierarchy violations, manning below 70%

UnitTreeCodec — JSON encode/decode with schema versioning and full round-trip fidelity

TemplateCubit — extended with instantiateDoctrinalTemplate, exportToJson, importFromJson

ValidationCubit — wraps validation engine, exposes findings by severity

DutyMos — extended to accept 4-character aviation AOC codes (e.g., 153A)

54 new tests (191 total)

Deferred to Phase 4: MIL-STD-2525D symbology engine, three-pane UI shell enhancements, validation findings as canvas node indicators, background Isolate offloading for validation.

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:
```
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:

┌─────────────────────────────────────────────────────────────────────┐
│ 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 (deferred to Phase 4)
Three-pane UI shell functional on desktop (basic shell from Phase 2; full enhancements deferred)
Runtime template reload mechanism operational (JSON codec + importFromJson)

Phase 4: Persistence, Validation Rules, & Export Engine ✅ COMPLETE (2026-08-09)

Status: Phase 4 reporting & analytics deliverables completed and merged to main. 263/263 tests passing. flutter analyze — No issues found. Branch: feature/phase-4-reporting-analytics → merged 2026-08-09.

Completed in this phase:

CommandEventStore — append-only event log with CommandEvent, CommandEventType, CommandPayloads

DeltaSynchronizer — offline-first sync helper with syncIfOnline() and isOnline control

IsolateValidationRunner — background-isolate wrapper for MtoeValidationEngine with ValidationResponse

ProtobufCodec — binary encode/decode with 12-byte UTOB header + zlib-compressed JSON payload

PdfChartExporter — pure-Dart PDF 1.4 org-chart generator (letter/A4/tabloid, UNCLASSIFIED banner)

ValidationCubit — extended with startIsolate(), disposeIsolate(), validateAsync()

HomeScreen — validation node indicators, PDF/binary export actions, findings inspector panel

72 new tests (263 total)

Deferred to Phase 5: Real network transport for DeltaSynchronizer, true Protobuf schema, single-transaction template instantiation, MIL-STD-2525D symbology 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: UI/CRUD Layer & Web Platform ✅ COMPLETE (2026-08-09)

Status: Phase 5 UI/CRUD layer and web platform support completed and merged to main. 263/263 tests passing. flutter analyze — No issues found.

Completed in this phase:

SoldierPosition entity — 31 built-in Army duty positions + user-defined custom positions

SoldierPositions Drift table + SoldierPositionsDao + DriftSoldierPositionsRepository

AppDatabase schema v2 migration — adds position_title to Personnel, creates soldier_positions table

Web platform: drift_worker.dart/js, sqlite3.wasm, platform-adaptive driftDatabase() connection

PersonnelRecord — extended with positionTitle, displayLabel, isAssigned, isFmc

UnitTreeCubit — full CRUD: addUnit, updateUnit, addSlot, updateSlot, deleteSlot, clearAll

PersonnelCubit — full CRUD: addPersonnel, updatePersonnel, deletePersonnel

AddEditPersonnelDialog — position picker with custom position management, MOS autocomplete

AddEditSlotDialog — slot creation/editing with MOS autocomplete and key-leader toggle

AddEditUnitDialog — unit creation/editing with echelon/branch/parent selectors

HomeScreen — full CRUD app bar actions, inspector CRUD buttons, export dialog with format/page-size selection

Deferred to hardening: MIL-STD-2525D symbology engine, SQLCipher encryption, undo/redo stack, multi-window support, PWA service worker, Android battery profiling.

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

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

43 KiB Raw Blame History Unescape Escape

Phased Development Plan

Flutter-Based Military Unit Task Organization (UTO) Manager

U.S. Army 2026 Doctrine — Cross-Platform Enterprise System

Overview

Architecture Summary

Phase 1: Architecture & Data Foundations ✅ COMPLETE (2026-08-07)

Weeks 1 – 4

1.1 — Project Scaffolding & Clean Architecture Setup (Week 1)

1.2 — Core Domain Entity Definitions (Weeks 1–2)

1.3 — Database Schema & Infrastructure Layer (Weeks 2–3)

1.4 — CI/CD Pipeline Configuration (Week 4)

Phase 1 Exit Criteria

Phase 2: Canvas Graphics Engine & Gesture Subsystem

Weeks 5 – 9

2.1 — CustomPainter Canvas Engine Foundation (Weeks 5–6)

2.2 — Reingold-Tilford Tree Layout Algorithm (Week 6)

2.3 — Quadtree Spatial Index (Week 7)

2.4 — Cross-Platform Drag-and-Drop State Machine (Weeks 7–9)

Phase 2 Exit Criteria

Phase 3: 2026 Doctrinal Templates & Symbology Engine ✅ COMPLETE (2026-08-09)

Weeks 10 – 14

3.1 — Doctrinal Template Library (Weeks 10–12)

3.2 — MIL-STD-2525D Symbology Engine (Weeks 12–14)

3.3 — Three-Pane UI Shell (Weeks 13–14)

Phase 3 Exit Criteria

Phase 4: Persistence, Validation Rules, & Export Engine ✅ COMPLETE (2026-08-09)

Weeks 15 – 19

4.1 — Full Persistence Integration & Offline-First Architecture (Weeks 15–16)

4.2 — Real-Time MTOE Domain Validation Engine (Weeks 16–18)

4.3 — Data Export Engine (Weeks 18–19)

Phase 4 Exit Criteria

Phase 5: UI/CRUD Layer & Web Platform ✅ COMPLETE (2026-08-09)

Weeks 20 – 24

5.1 — Performance Profiling & Rendering Optimization (Weeks 20–21)

5.2 — Heavy Computation Isolate Offloading (Week 21)

5.3 — Platform-Specific Hardening (Weeks 22–23)

5.4 — Security, Accessibility, & Final QA (Weeks 23–24)

5.5 — Release Package Assembly (Week 24)

Phase 5 Exit Criteria

Inter-Phase Dependency Map

Technology Stack Summary

Risk Register

43 KiB

Raw Blame History