missions/_docs/02_document/module-layout.md

# Module Layout

**Status**: derived-from-code (post-rename, forward-looking — see Verification Needed)
**Language**: csharp
**Layout Convention**: **custom** (layer-organized, NOT per-component-directory — see `## Verification Needed` below)
**Root**: `./` (no `src/` directory; .NET `Microsoft.NET.Sdk.Web` project at the repo root)
**Last Updated**: 2026-05-14

> **NOTE (forward-looking)**: file paths reflect the post-rename + post-GPS-Denied-removal state. Today's source still uses `Aircraft*` / `Flight*` / `Orthophoto*` / `GpsCorrection*` filenames, csproj is `Azaion.Flights.csproj`, and namespace is `Azaion.Flights.*`. Renames + drops are tracked under Jira AZ-EPIC children B5 (namespace), B6 (rename), B7 (GPS-Denied removal), B8 (HTTP routes), B9 (DB migration), B10 (Dockerfile / image / compose).

## Layout Rules

This codebase **does not** follow the "one directory per component" convention from the template. It is organized **horizontally** by architectural layer:

```
./
├── Auth/             ← cross-cutting (component 05_identity)
├── Controllers/      ← API surface (one file per feature component, 01 + 02)
├── Database/         ← persistence (component 04)
│   └── Entities/
├── DTOs/             ← payload types (split across components 01, 02, 06)
├── Enums/            ← domain enums (split across components 01, 02, 04)
├── Middleware/       ← cross-cutting (component 06_http_conventions)
├── Services/         ← business logic (one file per feature component, 01 + 02)
├── Entities/         ← EMPTY (scaffolding leftover)
├── Infrastructure/   ← EMPTY (scaffolding leftover)
├── Program.cs        ← composition root (component 07_host)
└── GlobalUsings.cs   ← composition root (component 07_host)
```

Consequence: each component's `Owns` glob is a SET OF FILE PATHS spanning multiple directories, NOT a single directory glob. There is no `shared/` directory; cross-cutting concerns (`05_identity`, `06_http_conventions`) own their root-level dirs (`Auth/`, `Middleware/`) directly.

The C# project has no separate per-component csproj — there is one project (post-rename: `Azaion.Missions.csproj`; today: `Azaion.Flights.csproj`) and effectively one root namespace (post-rename: `Azaion.Missions.*`). Other components reference each other through types directly; there is no compiled "Public API" boundary.

## Per-Component Mapping

### Component: 01_vehicle_catalog

- **Epic**: Jira AZ-EPIC (rename + multi-vehicle support)
- **Directory(ies)**: spread across `Controllers/`, `Services/`, `DTOs/`, `Enums/`
- **Public API** (types other components reference): `Services/VehicleService.cs` (consumed by `07_host` for DI registration; `02_mission_planning` consumes its existence semantics through the DB)
- **Owns (exclusive write)** (post-rename):
  - `Controllers/VehiclesController.cs`
  - `Services/VehicleService.cs`
  - `DTOs/CreateVehicleRequest.cs`
  - `DTOs/UpdateVehicleRequest.cs`
  - `DTOs/GetVehiclesQuery.cs`
  - `DTOs/SetDefaultRequest.cs`
- **Internal**: none — every file is publicly importable in C# without explicit visibility annotations
- **Imports from**: `04_persistence` (`AppDataConnection`, `Vehicle` entity, `VehicleType` enum, `FuelType` enum), `05_identity` (`[Authorize(Policy = "FL")]`), `06_http_conventions` (exception → middleware mapping is implicit)
- **Consumed by**: `02_mission_planning` (FK existence-check on `vehicle_id`), `07_host` (DI registration)

### Component: 02_mission_planning

- **Epic**: Jira AZ-EPIC
- **Directory(ies)**: spread across `Controllers/`, `Services/`, `DTOs/`, `Enums/`
- **Public API** (post-rename): `Services/MissionService.cs`, `Services/WaypointService.cs` (DI-registered in `07_host`)
- **Owns (exclusive write)** (post-rename):
  - `Controllers/MissionsController.cs`
  - `Services/MissionService.cs`
  - `Services/WaypointService.cs`
  - `DTOs/CreateMissionRequest.cs`
  - `DTOs/UpdateMissionRequest.cs`
  - `DTOs/GetMissionsQuery.cs`
  - `DTOs/CreateWaypointRequest.cs`
  - `DTOs/UpdateWaypointRequest.cs`
  - `DTOs/GeoPoint.cs`
- **Internal**: none
- **Imports from**: `04_persistence` (incl. `WaypointSource` + `WaypointObjective` enums), `05_identity`, `06_http_conventions` (`PaginatedResponse<T>`), `01_vehicle_catalog` (existence semantics through DB FK)
- **Consumed by**: `07_host` (DI), and external `autopilot` / `ui` (cross-service over HTTP)

### Component: 04_persistence

- **Epic**: Jira AZ-EPIC
- **Directory(ies)**: `Database/`, plus `Enums/ObjectStatus.cs` (cross-cutting status enum)
- **Public API**: `Database/AppDataConnection.cs` (the `DataConnection` type other components depend on), `Database/DatabaseMigrator.cs` (called by `07_host` at startup), all 7 entities under `Database/Entities/` (referenced by services + DTOs as row maps), the four persisted-column enums under `Enums/` (`VehicleType`, `FuelType`, `WaypointSource`, `WaypointObjective`, `ObjectStatus`)
- **Owns (exclusive write)** (post-rename):
  - `Database/AppDataConnection.cs`
  - `Database/DatabaseMigrator.cs`
  - `Database/Entities/Vehicle.cs`
  - `Database/Entities/Mission.cs`
  - `Database/Entities/Waypoint.cs`
  - `Database/Entities/MapObject.cs`
  - `Database/Entities/Media.cs` (borrowed schema)
  - `Database/Entities/Annotation.cs` (borrowed schema)
  - `Database/Entities/Detection.cs` (borrowed schema)
  - `Enums/VehicleType.cs` (persisted on `vehicles.type`; consumed by `01_vehicle_catalog` DTOs)
  - `Enums/FuelType.cs` (persisted on `vehicles.fuel_type`; consumed by `01_vehicle_catalog` DTOs)
  - `Enums/WaypointSource.cs` (persisted on `waypoints.waypoint_source`; consumed by `02_mission_planning` DTOs)
  - `Enums/WaypointObjective.cs` (persisted on `waypoints.waypoint_objective`; consumed by `02_mission_planning` DTOs)
  - `Enums/ObjectStatus.cs` (persisted on `map_objects.object_status`)
- **Internal**: none
- **Imports from**: nothing internal
- **Consumed by**: `01_vehicle_catalog`, `02_mission_planning`, `07_host`

### Component: 05_identity

- **Epic**: Jira AZ-EPIC
- **Directory(ies)**: `Auth/`
- **Public API**: `Auth/JwtExtensions.AddJwtAuth(...)` (called by `07_host`); the `"FL"` policy NAME (referenced as a string by feature controllers — string-typed dependency, NOT compile-checked)
- **Owns (exclusive write)**:
  - `Auth/JwtExtensions.cs`
- **Internal**: none
- **Imports from**: nothing internal
- **Consumed by**: `01_vehicle_catalog`, `02_mission_planning`, `07_host`

### Component: 06_http_conventions

- **Epic**: Jira AZ-EPIC
- **Directory(ies)**: `Middleware/`, plus `DTOs/ErrorResponse.cs` and `DTOs/PaginatedResponse.cs`
- **Public API**: `Middleware/ErrorHandlingMiddleware` (registered by `07_host`); `DTOs/PaginatedResponse<T>` (returned by `02_mission_planning`); `DTOs/ErrorResponse` is unused on the wire today (see component description Caveats #2)
- **Owns (exclusive write)**:
  - `Middleware/ErrorHandlingMiddleware.cs`
  - `DTOs/ErrorResponse.cs`
  - `DTOs/PaginatedResponse.cs`
- **Internal**: none
- **Imports from**: nothing internal
- **Consumed by**: `02_mission_planning` (`PaginatedResponse<T>`), `07_host` (middleware registration), all components implicitly (exception → status code mapping)

### Component: 07_host

- **Epic**: Jira AZ-EPIC
- **Directory(ies)**: repo root
- **Public API**: none (it is the runtime entry point)
- **Owns (exclusive write)**:
  - `Program.cs`
  - `GlobalUsings.cs`
- **Internal**: none
- **Imports from**: `04_persistence`, `05_identity`, `06_http_conventions`, `01_vehicle_catalog`, `02_mission_planning`
- **Consumed by**: nothing internal — invoked by the .NET runtime via `dotnet Azaion.Missions.dll` (post-rename) / `dotnet Azaion.Flights.dll` (today)

## Shared / Cross-Cutting

There is no `shared/` directory in this codebase. The role canonically taken by `shared/*` is filled by:

- **`05_identity`** (`Auth/`) — auth setup + named policies
- **`06_http_conventions`** (`Middleware/` + 2 DTOs) — error envelope + paginated response envelope
- **`04_persistence`** — provides shared `AppDataConnection` to all feature components

All five enums under `Enums/` (`VehicleType`, `FuelType`, `WaypointSource`, `WaypointObjective`, `ObjectStatus`) are owned by `04_persistence` because they are *persisted column types* — every one of them maps to an `INTEGER` column in the schema (`Database/DatabaseMigrator.cs`) and is referenced from a `04_persistence`-owned entity (`Vehicle`, `Waypoint`, `MapObject`). Feature components (`01`, `02`) consume them as foundation types, never own them. This was retagged on 2026-05-14 to resolve baseline findings F1 + F2 (see `_docs/02_document/architecture_compliance_baseline.md`); previously `VehicleType` / `FuelType` were tagged under `01` and `WaypointSource` / `WaypointObjective` under `02`, which created a Foundation ← Feature layering violation.

## Allowed Dependencies (layering)

Read top-to-bottom; an upper layer may import from a lower layer but NEVER the reverse.

| Layer | Components | May import from |
|-------|------------|-----------------|
| 4. Composition root | 07_host | 1, 2, 3 |
| 3. Feature surfaces | 01_vehicle_catalog, 02_mission_planning | 1, 2 |
| 2. Domain (none today) | — | 1 |
| 1. Foundation | 04_persistence, 05_identity, 06_http_conventions | (none) |

There is no "Domain" layer in this codebase — feature components are thin (controller + service + DTOs) and bind directly to persistence entities. This matches typical CRUD-style ASP.NET Core services and is the deliberate shape per `../../suite/_docs/02_missions.md`.

Violations of this table are **Architecture** findings in code-review Phase 7 (High severity).

## Layout Conventions (reference)

| Language | Root | Per-component path | Public API file | Test path |
|----------|------|-------------------|-----------------|-----------|
| C# (.NET) | `src/` (canonical) | `src/<Component>/` | `src/<Component>/<Component>.cs` (namespace root) | `tests/<Component>.Tests/` |
| **C# (this repo)** | `./` (NOT canonical) | spread by horizontal layer | (no per-component public-API file; types referenced directly) | **no tests project** |

## Verification Needed

- [ ] **Forward-looking file paths**: every "Owns" path above reflects the post-rename target (B5/B6/B7/B8). Today the files still have `Aircraft*` / `Flight*` / `Orthophoto*` / `GpsCorrection*` names. Implementers of B5–B10 should treat this layout as the spec for the rename, not the current ground truth. After B6 ships the layout matches the disk.
- [ ] **Layer-organized vs component-organized layout**: this codebase organizes files by horizontal layer (`Controllers/`, `Services/`, `DTOs/`, `Enums/`) not by feature component. The Owns globs are composed from multiple directories, which is unusual and means a single directory rename would touch multiple components' Owns. **Question for user**: keep as-is (matches the rest of the suite's .NET services? — needs verification against `annotations` and `admin` layout) or should a future refactor move toward feature-folders?
- [ ] **`Entities/` and `Infrastructure/` at the root are EMPTY** — `Entities/` is shadowed by `Database/Entities/`. With GPS-Denied moving out of this repo, the historical "earmarked for orthophoto path resolver" reason is gone. **Question for user**: delete both empty dirs as part of B5?
- [ ] **No `src/` directory** — the .NET project sits at the repo root. `coderule.mdc` says "For existing projects, follow the established directory structure." → established structure is "no `src/`"; this layout DOC respects that. Confirm we should NOT move it.
- [ ] **Policy name is string-typed** — feature controllers reference `"FL"` as a raw string. A typo would silently turn into a permanent 403. **Question for user**: should `05_identity` expose a typed `PolicyNames.FL` constant? Cheap improvement; not a blocker for documentation.
- [ ] **Cross-component DTO clusters**: `DTOs/` directory mixes payloads from `01`, `02`, and `06`. Owns globs are file-by-file. Acceptable for now; a future refactor could split into per-component subfolders (e.g. `DTOs/Vehicle/`, `DTOs/Mission/`, `DTOs/Common/`).
- [ ] **No `tests/` project exists** (per `../../suite/_docs/_process_leftovers/2026-04-22_ci-unit-test-lane-missing-projects.md`). Test-spec / test-implement steps in autodev will need to create a sibling `Azaion.Missions.Tests` csproj — at `tests/Azaion.Missions.Tests/` (suite-canonical) or somewhere else? Confirm.
- [ ] **Cycles spanning components**: none detected. The `Vehicle → Mission → Waypoint` association graph is intra-component (entirely inside `04_persistence`).