# 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 (flutter_bloc) |
| Drag-and-Drop | Flutter DragTarget / Draggable |
| Local Database | Drift v2 (SQLite / IndexedDB) — schema v2 |
| Web DB Worker | drift_worker.js + sqlite3.wasm |
| Encryption | SQLCipher *(planned)* |
| Symbology (Web) | milsymbol.js via dart:js_interop *(planned)* |
| Symbology (Native) | path_drawing + SVG assets + LRU cache *(planned)* |
| Background Compute | Dart Isolates (IsolateValidationRunner) |
| Serialization | JSON (UnitTreeCodec) + Binary (ProtobufCodec) |
| PDF Export | Pure-Dart PDF 1.4 (PdfChartExporter) |
| 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
```