# gs-citizentech-drenaai/drenaai-api architecture

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

- Interactive diagram: https://gitdiagram.com/gs-citizentech-drenaai/drenaai-api
- Repository: https://github.com/gs-citizentech-drenaai/drenaai-api

## Overview

DrenaAi is a .NET urban-maintenance API for flood prevention. Residents submit reports and devices send drain readings; the API evaluates severity and neighborhood risk, computes an IPC score, persists reports and telemetry, and exposes a prioritized operations queue. Authentication, status history, and device-key security support those flows. The README documents climate/topographic and computer-vision capabilities; source excerpts show the report and telemetry service calls. Unsampled endpoint details are represented only where the README or source index supports them.

Main entry points: [`DrenaAi.Api/Contexts/Ocorrencias/OcorrenciaService.cs`](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Ocorrencias/OcorrenciaService.cs) (Occurrence service), [`DrenaAi.Api/Contexts/Telemetrias/TelemetriaService.cs`](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Telemetrias/TelemetriaService.cs) (Telemetry service), [`DrenaAi.Api/Program.cs`](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Program.cs) (Web API), [`DrenaAi.Api/Controllers/TelemetriaController.cs`](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/TelemetriaController.cs) (Telemetry endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_api["Web API<br/>[Program.cs]"]
  node_auth["Authentication<br/>[AuthController.cs]"]
  node_occ_api["Occurrence endpoints"]
  node_queue_api["Priority queue<br/>[FilaController.cs]"]
  node_severity_api["Severity endpoint"]
  node_telemetry_api["Telemetry endpoints"]
end

subgraph group_reports["Occurrence management"]
  node_occ_service["Occurrence service"]
  node_occurrence["Occurrence lifecycle<br/>[Ocorrencia.cs]"]
  node_status_history["Status history<br/>[HistoricoStatus.cs]"]
  node_address["Location value object<br/>[Endereco.cs]"]
end

subgraph group_risk["Risk and prioritization"]
  node_ipc["IPC calculator"]
  node_ai_mock["AI mock integration"]
  node_ai_http["AI HTTP integration"]
end

subgraph group_telemetry["IoT telemetry"]
  node_telemetry_service["Telemetry service"]
  node_sensor["Drain sensor model<br/>[SensorBueiro.cs]"]
end

subgraph group_platform["Persistence and security"]
  node_auth_service["Account service<br/>[AuthService.cs]"]
  node_api_key["Device key filter"]
  node_sanitizer["PII sanitizer"]
  node_store[("Oracle data store<br/>[AppDbContext.cs]")]
  node_errors["Exception middleware"]
end

node_resident(("Resident app"))
node_device(("ESP32 device"))
node_operator(("Operations user"))
node_vision["Computer vision"]
node_climate["Climate risk ML"]

node_resident -->|"registers or logs in"| node_auth
node_resident -->|"submits reports"| node_occ_api
node_device -->|"sends readings"| node_telemetry_api
node_operator -->|"views queue"| node_queue_api
node_api -->|"registers service"| node_auth_service
node_api -->|"registers service"| node_occ_service
node_api -->|"registers service"| node_telemetry_service
node_auth -->|"delegates to"| node_auth_service
node_auth_service -->|"reads and writes"| node_store
node_occ_api -->|"delegates to"| node_occ_service
node_queue_api -->|"queries queue"| node_occ_service
node_severity_api -.->|"requests analysis"| node_ai_mock
node_occ_service -->|"requests severity and risk"| node_ai_mock
node_occ_service -->|"calculates priority"| node_ipc
node_occ_service -->|"reads and writes"| node_store
node_occ_service -->|"sanitizes report text"| node_sanitizer
node_occurrence -->|"uses location"| node_address
node_occurrence -->|"records transitions"| node_status_history
node_telemetry_api -->|"applies device key"| node_api_key
node_telemetry_api -->|"delegates to"| node_telemetry_service
node_telemetry_service -->|"reads and writes"| node_store
node_telemetry_service -->|"requests neighborhood risk"| node_ai_mock
node_telemetry_service -->|"calculates priority"| node_ipc
node_telemetry_service -->|"records readings"| node_sensor
node_ai_http -.->|"requests analysis"| node_vision
node_ai_http -.->|"requests forecast"| node_climate
node_api -.->|"uses middleware"| node_errors

click node_api "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Program.cs"
click node_auth "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/AuthController.cs"
click node_occ_api "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/OcorrenciasController.cs"
click node_queue_api "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/FilaController.cs"
click node_severity_api "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/SeveridadeController.cs"
click node_telemetry_api "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/TelemetriaController.cs"
click node_auth_service "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Usuarios/AuthService.cs"
click node_occ_service "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Ocorrencias/OcorrenciaService.cs"
click node_occurrence "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Ocorrencias/Ocorrencia.cs"
click node_status_history "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Ocorrencias/HistoricoStatus.cs"
click node_address "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Ocorrencias/Endereco.cs"
click node_ipc "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Priorizacao/CalculadoraIpcService.cs"
click node_ai_mock "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Priorizacao/IntegracaoIaMockService.cs"
click node_ai_http "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Priorizacao/IntegracaoIaHttpService.cs"
click node_telemetry_service "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Telemetrias/TelemetriaService.cs"
click node_sensor "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Telemetrias/SensorBueiro.cs"
click node_api_key "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Security/ApiKeyAuthFilter.cs"
click node_sanitizer "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Security/PiiSanitizerService.cs"
click node_store "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Data/AppDbContext.cs"
click node_errors "https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Middlewares/GlobalExceptionMiddleware.cs"

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_api,node_auth,node_occ_api,node_queue_api,node_severity_api,node_telemetry_api,node_operator toneBlue
class node_occ_service,node_occurrence,node_status_history,node_address toneAmber
class node_ipc,node_ai_mock,node_ai_http toneMint
class node_telemetry_service,node_sensor toneRose
class node_auth_service,node_api_key,node_sanitizer,node_store,node_errors,node_resident,node_device,node_vision,node_climate toneIndigo
```

## Components

### API and access

- [Web API](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Program.cs): `DrenaAi.Api/Program.cs`
- [Authentication](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/AuthController.cs): `DrenaAi.Api/Controllers/AuthController.cs`
- [Occurrence endpoints](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/OcorrenciasController.cs): `DrenaAi.Api/Controllers/OcorrenciasController.cs`
- [Priority queue](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/FilaController.cs): `DrenaAi.Api/Controllers/FilaController.cs`
- [Severity endpoint](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/SeveridadeController.cs): `DrenaAi.Api/Controllers/SeveridadeController.cs`
- [Telemetry endpoints](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Controllers/TelemetriaController.cs): `DrenaAi.Api/Controllers/TelemetriaController.cs`

### Occurrence management

- [Occurrence service](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Ocorrencias/OcorrenciaService.cs): `DrenaAi.Api/Contexts/Ocorrencias/OcorrenciaService.cs`
- [Occurrence lifecycle](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Ocorrencias/Ocorrencia.cs): `DrenaAi.Api/Contexts/Ocorrencias/Ocorrencia.cs`
- [Status history](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Ocorrencias/HistoricoStatus.cs): `DrenaAi.Api/Contexts/Ocorrencias/HistoricoStatus.cs`
- [Location value object](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Ocorrencias/Endereco.cs): `DrenaAi.Api/Contexts/Ocorrencias/Endereco.cs`

### Risk and prioritization

- [IPC calculator](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Priorizacao/CalculadoraIpcService.cs): `DrenaAi.Api/Contexts/Priorizacao/CalculadoraIpcService.cs`
- [AI mock integration](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Priorizacao/IntegracaoIaMockService.cs): `DrenaAi.Api/Contexts/Priorizacao/IntegracaoIaMockService.cs`
- [AI HTTP integration](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Priorizacao/IntegracaoIaHttpService.cs): `DrenaAi.Api/Contexts/Priorizacao/IntegracaoIaHttpService.cs`

### IoT telemetry

- [Telemetry service](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Telemetrias/TelemetriaService.cs): `DrenaAi.Api/Contexts/Telemetrias/TelemetriaService.cs`
- [Drain sensor model](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Telemetrias/SensorBueiro.cs): `DrenaAi.Api/Contexts/Telemetrias/SensorBueiro.cs`

### Persistence and security

- [Account service](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Contexts/Usuarios/AuthService.cs): `DrenaAi.Api/Contexts/Usuarios/AuthService.cs`
- [Device key filter](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Security/ApiKeyAuthFilter.cs): `DrenaAi.Api/Security/ApiKeyAuthFilter.cs`
- [PII sanitizer](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Security/PiiSanitizerService.cs): `DrenaAi.Api/Security/PiiSanitizerService.cs`
- [Oracle data store](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Data/AppDbContext.cs): `DrenaAi.Api/Data/AppDbContext.cs`
- [Exception middleware](https://github.com/gs-citizentech-drenaai/drenaai-api/blob/main/DrenaAi.Api/Middlewares/GlobalExceptionMiddleware.cs): `DrenaAi.Api/Middlewares/GlobalExceptionMiddleware.cs`

### Other components

- **Resident app**
- **ESP32 device**
- **Operations user**
- **Computer vision**
- **Climate risk ML**

## Connections

- Resident app → Authentication: registers or logs in
- Resident app → Occurrence endpoints: submits reports
- ESP32 device → Telemetry endpoints: sends readings
- Operations user → Priority queue: views queue
- Web API → Account service: registers service (evidence: `DrenaAi.Api/Program.cs`)
- Web API → Occurrence service: registers service (evidence: `DrenaAi.Api/Program.cs`)
- Web API → Telemetry service: registers service (evidence: `DrenaAi.Api/Program.cs`)
- Authentication → Account service: delegates to (evidence: `DrenaAi.Api/Controllers/AuthController.cs`)
- Account service → Oracle data store: reads and writes (evidence: `DrenaAi.Api/Contexts/Usuarios/AuthService.cs`)
- Occurrence endpoints → Occurrence service: delegates to (evidence: `DrenaAi.Api/Controllers/OcorrenciasController.cs`)
- Priority queue → Occurrence service: queries queue (evidence: `DrenaAi.Api/Controllers/FilaController.cs`)
- Severity endpoint → AI mock integration: requests analysis
- Occurrence service → AI mock integration: requests severity and risk (evidence: `DrenaAi.Api/Contexts/Ocorrencias/OcorrenciaService.cs`)
- Occurrence service → IPC calculator: calculates priority (evidence: `DrenaAi.Api/Contexts/Ocorrencias/OcorrenciaService.cs`)
- Occurrence service → Oracle data store: reads and writes (evidence: `DrenaAi.Api/Contexts/Ocorrencias/OcorrenciaService.cs`)
- Occurrence service → PII sanitizer: sanitizes report text (evidence: `DrenaAi.Api/Contexts/Ocorrencias/OcorrenciaService.cs`)
- Occurrence lifecycle → Location value object: uses location (evidence: `DrenaAi.Api/Contexts/Ocorrencias/Ocorrencia.cs`)
- Occurrence lifecycle → Status history: records transitions (evidence: `DrenaAi.Api/Contexts/Ocorrencias/Ocorrencia.cs`)
- Telemetry endpoints → Device key filter: applies device key (evidence: `DrenaAi.Api/Controllers/TelemetriaController.cs`)
- Telemetry endpoints → Telemetry service: delegates to (evidence: `DrenaAi.Api/Controllers/TelemetriaController.cs`)
- Telemetry service → Oracle data store: reads and writes (evidence: `DrenaAi.Api/Contexts/Telemetrias/TelemetriaService.cs`)
- Telemetry service → AI mock integration: requests neighborhood risk (evidence: `DrenaAi.Api/Contexts/Telemetrias/TelemetriaService.cs`)
- Telemetry service → IPC calculator: calculates priority (evidence: `DrenaAi.Api/Contexts/Telemetrias/TelemetriaService.cs`)
- Telemetry service → Drain sensor model: records readings (evidence: `DrenaAi.Api/Contexts/Telemetrias/TelemetriaService.cs`)
- AI HTTP integration → Computer vision: requests analysis
- AI HTTP integration → Climate risk ML: requests forecast
- Web API → Exception middleware: uses middleware (evidence: `DrenaAi.Api/Program.cs`)
