# Codebase discovery — Azaion.Annotations

## Canonical product documentation (external)

Suite-level API and integration reference (maintained with the monorepo):

`/Users/obezdienie001/dev/azaion/suite/_docs/01_annotations.md`  
(Relative from this repo: `../_docs/01_annotations.md`.)

This `_docs/02_document/` run is **bottom-up from code**; keep `01_annotations.md` aligned when HTTP contracts or integration behavior change.

---

## Directory tree (source)

```
annotations/
├── README.md
├── src/
│   ├── Azaion.Annotations.csproj
│   ├── Dockerfile
│   ├── GlobalUsings.cs
│   ├── Program.cs
│   ├── Auth/
│   ├── Controllers/
│   ├── Database/
│   │   ├── AppDataConnection.cs
│   │   ├── DatabaseMigrator.cs
│   │   └── Entities/
│   ├── DTOs/
│   ├── Enums/
│   ├── Middleware/
│   └── Services/
└── _docs/
```

Ignored per scan policy: `bin/`, `obj/`, `.git`, `node_modules`, `__pycache__`.

---

## Tech stack

| Area | Choice |
|------|--------|
| Language | C# / .NET (`net10.0` in csproj) |
| Host | ASP.NET Core minimal hosting + controllers |
| ORM / DB | Linq2DB + Npgsql → PostgreSQL |
| Auth | JWT Bearer (`Microsoft.AspNetCore.Authentication.JwtBearer`) |
| Messaging | RabbitMQ Streams (`RabbitMQ.Stream.Client`), MessagePack |
| API docs | Swashbuckle (Swagger / OpenAPI) |
| Hashing | `System.IO.Hashing` (annotation id / media paths) |

---

## Package manifest

- `src/Azaion.Annotations.csproj` — single web project.

---

## Config and operations

| Artifact | Role |
|----------|------|
| `src/Dockerfile` | Container build |
| `Program.cs` | `DATABASE_URL`, `JWT_ISSUER` / `JWT_AUDIENCE` / `JWT_JWKS_URL`, `CorsConfig:*`, RabbitMQ env vars (`RABBITMQ_*`), migrator on startup. All required vars are resolved through `ConfigurationResolver` (fail-fast). |
| `.vscode/launch.json` | Local debugging (if present) |

No `.github/workflows` in this repository (CI may live in suite/monorepo).

---

## Entry points

- **`Program.cs`** — service registration, JWT, CORS, Swagger, `DatabaseMigrator.Migrate`, middleware pipeline, `MapControllers()`, `/health`.

---

## Tests

No `*.Tests.csproj` or `tests/` tree in this workspace — **no automated test project** discovered.

---

## Existing documentation in repo

- Root `README.md` — points to suite `01_annotations.md`.
- `src/README.md` — short service blurb + link to root README.

---

## Module boundaries (revised — aligned with `01_annotations.md`)

The suite file is organized around **annotation lifecycle**, **media**, **settings/camera**, **SSE**, **RabbitMQ sync**, and **auth** (JWT refresh). The codebase splits the same concerns across controllers/services; **dataset** and **detection classes** are additional HTTP surfaces referenced from suite `09_dataset_explorer.md` / UI.

| # | Module (doc file) | Primary code | Suite `01_annotations.md` anchor |
|---|-------------------|--------------|-----------------------------------|
| 1 | `wire-enums.md` | `src/Enums/*` | “Wire format”, enum tables |
| 2 | `database-layer.md` | `src/Database/*` | Annotation identity, tables, `SilentDetection` / `GenerateAnnotatedImage` columns |
| 3 | `common-infrastructure.md` | `PathResolver`, `ErrorHandlingMiddleware`, `PaginatedResponse`, `ErrorResponse`, `GlobalUsings.cs` | File paths for image/label/thumb/results; error JSON shape |
| 4 | `auth-identity.md` | `JwtExtensions` (verifier-only over admin's JWKS) | JWT forward only — refresh is admin's responsibility (annotations no longer hosts `/auth/refresh`) |
| 5 | `media-service.md` | `MediaService`, `MediaController`, media DTOs | §7–10 POST/GET/DELETE media, batch upload |
| 6 | `annotations-service.md` | `AnnotationService`, `AnnotationsController` (REST + static files, not SSE) | §1–6 annotations CRUD/query |
| 7 | `dataset-service.md` | `DatasetService`, `DatasetController`, dataset DTOs | Cross-ref §3 note (DATASET); `09_dataset_explorer.md` |
| 8 | `settings-metadata-service.md` | `SettingsService`, `SettingsController`, `ClassesController`, settings DTOs | §11–12 camera; directories/system/user settings; GET `/classes` |
| 9 | `sse-realtime.md` | `AnnotationEventService`, SSE action on `AnnotationsController` | §SSE `GET /annotations/events`, `AnnotationEvent` |
| 10 | `rabbitmq-stream-sync.md` | `FailsafeProducer`, `RabbitMqConfig`, `DTOs/QueueMessages.cs`, queue entity | §Annotation Sync, Failsafe, Stream |
| 11 | `composition-program.md` | `Program.cs` | Wiring, env defaults, startup migrate |

**DTOs** (`src/DTOs/`) are documented **inside the module that owns the HTTP contract**, with cross-links (no separate monolithic “DTOs” module).

See `modules/README.md` for the same index and file naming.

---

## Module dependency graph (revised)

```mermaid
flowchart BT
  WE[wire-enums]
  DB[database-layer]
  CI[common-infrastructure]
  AUTH[auth-identity]
  MEDIA[media-service]
  ANN[annotations-service]
  DS[dataset-service]
  SET[settings-metadata-service]
  SSE[sse-realtime]
  RMQ[rabbitmq-stream-sync]
  PRG[composition-program]

  WE --> DB
  DB --> CI
  DB --> MEDIA
  DB --> ANN
  DB --> DS
  DB --> SET
  CI --> MEDIA
  CI --> ANN
  AUTH --> MEDIA
  AUTH --> ANN
  AUTH --> DS
  AUTH --> SET
  MEDIA --> ANN
  ANN --> SSE
  ANN --> RMQ
  SET --> CI
  SSE --> ANN
  RMQ --> ANN
  RMQ --> MEDIA
  RMQ --> DB
  MEDIA --> PRG
  ANN --> PRG
  DS --> PRG
  SET --> PRG
  SSE --> PRG
  RMQ --> PRG
  AUTH --> PRG
  CI --> PRG
```

Edges are “depends on for types, DB, paths, or events” (approximate). `ClassesController` reads DB directly — captured under **settings-metadata-service** for doc cohesion (small surface).

---

## Topological order (document skill Step 1)

1. `wire-enums`  
2. `database-layer`  
3. `common-infrastructure`  
4. `auth-identity`  
5. `media-service`  
6. `annotations-service`  
7. `dataset-service`  
8. `settings-metadata-service`  
9. `sse-realtime`  
10. `rabbitmq-stream-sync`  
11. `composition-program`  

---

## Notes for downstream steps

- **Component assembly (Step 2):** expect components such as “Annotations + sync”, “Media”, “Dataset”, “Settings”, “Platform (auth+db+infra)” — refine with user confirmation (BLOCKING gate).
- **RabbitMQ:** `RabbitMqConfig` class lives in `FailsafeProducer.cs`; document in `rabbitmq-stream-sync` module.

---

## Suite spec cross-check (`suite/_docs/01_annotations.md`)

Canonical product/API narrative for this service. Use it when writing module and component docs.

| Topic in suite doc | Adds context for this repo |
|--------------------|------------------------------|
| Annotation identity (hash id, image + YOLO label, `Time` / `CreatedDate`) | `annotations-service` + `database-layer` + `common-infrastructure` (`PathResolver`) |
| Wire enums as integers | `wire-enums` module |
| REST §1–6 vs §7–10 | `annotations-service` vs `media-service` |
| Settings §11–12, directories | `settings-metadata-service` |
| SSE | `sse-realtime` |
| Failsafe + RabbitMQ Stream | `rabbitmq-stream-sync` |
| Dataset note (DATASET permission) | `dataset-service` |

**Drifts spotted (suite vs current code)** — reconcile in suite or in code as you prefer:

1. **POST /annotations user id:** Suite lists `UserId` on request body; code uses JWT `NameIdentifier` (`annotations-service`).
2. **GET /annotations filter:** Suite lists `missionId`; code has `FlightId` and a partial filter — see `annotations-service` module.

Module docs (`modules/*.md`) carry contract detail per slice; this section stays the cross-file index.