# abuomar121/sair-server architecture

> Architecture diagram of the GitHub repository abuomar121/sair-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abuomar121/sair-server
- Repository: https://github.com/abuomar121/sair-server

## Overview

SAIR is a Dart Frog backend for accident reporting. Citizens register or log in, create reports with location details, attach media, and track reports; officers or admins change report status, which generates notifications. Admins can also list users. The README documents the HTTP routes, domain/application separation, JWT authentication, and JSON persistence, but no source excerpts were provided, so internal call relationships are omitted where the README does not establish them.

Main entry points: [`routes/_middleware.dart`](https://github.com/abuomar121/sair-server/blob/main/routes/_middleware.dart) (Auth middleware), [`lib/src/features/reports/report_repository_impl.dart`](https://github.com/abuomar121/sair-server/blob/main/lib/src/features/reports/report_repository_impl.dart) (Report repository), [`routes/auth`](https://github.com/abuomar121/sair-server/tree/main/routes/auth) (Auth endpoints), [`routes/reports`](https://github.com/abuomar121/sair-server/tree/main/routes/reports) (Report endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transport["HTTP API"]
  node_auth_routes["Auth endpoints"]
  node_me_route["User context<br/>[me.dart]"]
  node_report_routes["Report endpoints"]
  node_media_route["Report media<br/>[media.dart]"]
  node_status_route["Status update<br/>[status.dart]"]
  node_notification_route["Notifications endpoint<br/>[index.dart]"]
  node_admin_route["Admin users<br/>[users.dart]"]
end

subgraph group_identity["Identity and access"]
  node_middleware["Auth middleware<br/>[_middleware.dart]"]
  node_auth_service["Authentication<br/>[auth_service.dart]"]
  node_jwt["JWT service<br/>[jwt_service.dart]"]
end

subgraph group_reports["Report workflow"]
  node_create_report["Create report use case<br/>[create_report.dart]"]
  node_report_repository["Report repository"]
  node_notification_service["Notification service"]
  node_image_service["Image service<br/>[image_service.dart]"]
end

subgraph group_platform["Domain and persistence"]
  node_report_model["Report model<br/>[report.dart]"]
  node_user_model["User model<br/>[app_user.dart]"]
  node_notification_model["Notification model"]
  node_report_status["Status lifecycle<br/>[report_status.dart]"]
  node_report_contract["Report contract"]
  node_json_backend[("JSON backend<br/>[json_backend.dart]")]
  node_json_db[("JSON database<br/>[json_db.dart]")]
  node_firestore_backend[("Firestore adapter")]
end

node_citizen(("Citizen"))
node_officer(("Officer / admin"))

node_citizen -->|"registers / logs in"| node_auth_routes
node_citizen -->|"creates / tracks"| node_report_routes
node_citizen -->|"attaches media"| node_media_route
node_citizen -->|"checks updates"| node_notification_route
node_officer -->|"updates status"| node_status_route
node_officer -->|"lists users"| node_admin_route
node_auth_routes -.->|"handles auth"| node_auth_service
node_middleware -->|"verifies token"| node_jwt
node_middleware -->|"resolves identity"| node_me_route
node_report_routes -.->|"creates report"| node_create_report
node_status_route -->|"generates notification"| node_notification_service
node_media_route -.->|"handles media"| node_image_service
node_report_repository -.->|"uses JSON storage"| node_json_backend
node_json_backend -.->|"persists data"| node_json_db
node_report_repository -.->|"adapter alternative"| node_firestore_backend

click node_auth_routes "https://github.com/abuomar121/sair-server/tree/main/routes/auth"
click node_me_route "https://github.com/abuomar121/sair-server/blob/main/routes/me.dart"
click node_report_routes "https://github.com/abuomar121/sair-server/tree/main/routes/reports"
click node_media_route "https://github.com/abuomar121/sair-server/blob/main/routes/reports/%5Bid%5D/media.dart"
click node_status_route "https://github.com/abuomar121/sair-server/blob/main/routes/reports/%5Bid%5D/status.dart"
click node_notification_route "https://github.com/abuomar121/sair-server/blob/main/routes/notifications/index.dart"
click node_admin_route "https://github.com/abuomar121/sair-server/blob/main/routes/admin/users.dart"
click node_middleware "https://github.com/abuomar121/sair-server/blob/main/routes/_middleware.dart"
click node_auth_service "https://github.com/abuomar121/sair-server/blob/main/lib/src/features/auth/auth_service.dart"
click node_jwt "https://github.com/abuomar121/sair-server/blob/main/lib/src/security/jwt_service.dart"
click node_create_report "https://github.com/abuomar121/sair-server/blob/main/lib/src/application/usecases/create_report.dart"
click node_report_repository "https://github.com/abuomar121/sair-server/blob/main/lib/src/features/reports/report_repository_impl.dart"
click node_notification_service "https://github.com/abuomar121/sair-server/blob/main/lib/src/features/notifications/notification_service.dart"
click node_image_service "https://github.com/abuomar121/sair-server/blob/main/lib/src/features/common/image_service.dart"
click node_report_model "https://github.com/abuomar121/sair-server/blob/main/lib/src/domain/entities/report.dart"
click node_user_model "https://github.com/abuomar121/sair-server/blob/main/lib/src/domain/entities/app_user.dart"
click node_notification_model "https://github.com/abuomar121/sair-server/blob/main/lib/src/domain/entities/app_notification.dart"
click node_report_status "https://github.com/abuomar121/sair-server/blob/main/lib/src/domain/constants/report_status.dart"
click node_report_contract "https://github.com/abuomar121/sair-server/blob/main/lib/src/domain/repositories/report_repository.dart"
click node_json_backend "https://github.com/abuomar121/sair-server/blob/main/lib/src/persistence/json_backend.dart"
click node_json_db "https://github.com/abuomar121/sair-server/blob/main/lib/src/persistence/json_db.dart"
click node_firestore_backend "https://github.com/abuomar121/sair-server/blob/main/lib/src/persistence/firestore_backend.dart"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth_routes,node_me_route,node_report_routes,node_media_route,node_status_route,node_notification_route,node_admin_route toneBlue
class node_middleware,node_auth_service,node_jwt toneAmber
class node_create_report,node_report_repository,node_notification_service,node_image_service toneMint
class node_report_model,node_user_model,node_notification_model,node_report_status,node_report_contract,node_json_backend,node_json_db,node_firestore_backend toneRose
class node_citizen,node_officer toneIndigo
```

## Components

### HTTP API

- [Auth endpoints](https://github.com/abuomar121/sair-server/tree/main/routes/auth): `routes/auth`
- [User context](https://github.com/abuomar121/sair-server/blob/main/routes/me.dart): `routes/me.dart`
- [Report endpoints](https://github.com/abuomar121/sair-server/tree/main/routes/reports): `routes/reports`
- [Report media](https://github.com/abuomar121/sair-server/blob/main/routes/reports/%5Bid%5D/media.dart): `routes/reports/[id]/media.dart`
- [Status update](https://github.com/abuomar121/sair-server/blob/main/routes/reports/%5Bid%5D/status.dart): `routes/reports/[id]/status.dart`
- [Notifications endpoint](https://github.com/abuomar121/sair-server/blob/main/routes/notifications/index.dart): `routes/notifications/index.dart`
- [Admin users](https://github.com/abuomar121/sair-server/blob/main/routes/admin/users.dart): `routes/admin/users.dart`

### Identity and access

- [Auth middleware](https://github.com/abuomar121/sair-server/blob/main/routes/_middleware.dart): `routes/_middleware.dart`
- [Authentication](https://github.com/abuomar121/sair-server/blob/main/lib/src/features/auth/auth_service.dart): `lib/src/features/auth/auth_service.dart`
- [JWT service](https://github.com/abuomar121/sair-server/blob/main/lib/src/security/jwt_service.dart): `lib/src/security/jwt_service.dart`

### Report workflow

- [Create report use case](https://github.com/abuomar121/sair-server/blob/main/lib/src/application/usecases/create_report.dart): `lib/src/application/usecases/create_report.dart`
- [Report repository](https://github.com/abuomar121/sair-server/blob/main/lib/src/features/reports/report_repository_impl.dart): `lib/src/features/reports/report_repository_impl.dart`
- [Notification service](https://github.com/abuomar121/sair-server/blob/main/lib/src/features/notifications/notification_service.dart): `lib/src/features/notifications/notification_service.dart`
- [Image service](https://github.com/abuomar121/sair-server/blob/main/lib/src/features/common/image_service.dart): `lib/src/features/common/image_service.dart`

### Domain and persistence

- [Report model](https://github.com/abuomar121/sair-server/blob/main/lib/src/domain/entities/report.dart): `lib/src/domain/entities/report.dart`
- [User model](https://github.com/abuomar121/sair-server/blob/main/lib/src/domain/entities/app_user.dart): `lib/src/domain/entities/app_user.dart`
- [Notification model](https://github.com/abuomar121/sair-server/blob/main/lib/src/domain/entities/app_notification.dart): `lib/src/domain/entities/app_notification.dart`
- [Status lifecycle](https://github.com/abuomar121/sair-server/blob/main/lib/src/domain/constants/report_status.dart): `lib/src/domain/constants/report_status.dart`
- [Report contract](https://github.com/abuomar121/sair-server/blob/main/lib/src/domain/repositories/report_repository.dart): `lib/src/domain/repositories/report_repository.dart`
- [JSON backend](https://github.com/abuomar121/sair-server/blob/main/lib/src/persistence/json_backend.dart): `lib/src/persistence/json_backend.dart`
- [JSON database](https://github.com/abuomar121/sair-server/blob/main/lib/src/persistence/json_db.dart): `lib/src/persistence/json_db.dart`
- [Firestore adapter](https://github.com/abuomar121/sair-server/blob/main/lib/src/persistence/firestore_backend.dart): `lib/src/persistence/firestore_backend.dart`

### Other components

- **Citizen**
- **Officer / admin**

## Connections

- Citizen → Auth endpoints: registers / logs in (evidence: `README.md`)
- Citizen → Report endpoints: creates / tracks (evidence: `README.md`)
- Citizen → Report media: attaches media (evidence: `README.md`)
- Citizen → Notifications endpoint: checks updates (evidence: `README.md`)
- Officer / admin → Status update: updates status (evidence: `README.md`)
- Officer / admin → Admin users: lists users (evidence: `README.md`)
- Auth endpoints → Authentication: handles auth
- Auth middleware → JWT service: verifies token (evidence: `README.md`)
- Auth middleware → User context: resolves identity (evidence: `README.md`)
- Report endpoints → Create report use case: creates report
- Status update → Notification service: generates notification (evidence: `README.md`)
- Report media → Image service: handles media
- Report repository → JSON backend: uses JSON storage
- JSON backend → JSON database: persists data
- Report repository → Firestore adapter: adapter alternative (evidence: `README.md`)
