mtkell
/
uto_manager
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
uto_manager/phased_development_plan.md

38 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

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

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
  • 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

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