# 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)