# sos-rs/backend architecture

> Architecture diagram of the GitHub repository sos-rs/backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sos-rs/backend
- Repository: https://github.com/sos-rs/backend

## Overview

#### Purpose and runtime
This is a NestJS/Node.js REST backend for coordinating flood-relief shelters, volunteers, donations, supply inventory, and distribution in Rio Grande do Sul. It runs as a modular API application, entering through `src/main.ts` and composing features in `src/app.module.ts`. Endpoint contract detail is in `docs/endpoints.md`.

#### API and feature boundaries
Nest controllers expose HTTP operations; paired services contain domain and persistence workflows. Major bounded areas are:
- Shelters, search, capacities, and pets: `src/shelter/shelter.controller.ts`, `src/shelter/shelter.service.ts`, `src/shelter/ShelterSearch.ts`.
- Supply catalog, categories, and per-shelter stock: `src/supply/supply.service.ts`, `src/supply-categories/supply-categories.service.ts`, `src/shelter-supply/shelter-supply.service.ts`.
- Donation ordering and partner/distribution coordination: `src/donation-order/donation-order.controller.ts`, `src/partners/partners.service.ts`, `src/dashboard/dashboard.service.ts`.
- Shelter managers, supporters, and general users: `src/shelter-managers/shelter-managers.service.ts`, `src/supporters/supporters.service.ts`, `src/users/users.service.ts`.

#### Identity and authorization
Sessions issue and validate JWT-backed authentication, with strategy-based identity extraction. Role/scope guards protect routes for users, staff, administrators, distribution centers, and applicants. Relevant paths: `src/sessions/sessions.module.ts`, `src/sessions/jwt.strategy.ts`, `src/guards/jwt-auth.guard.ts`, `src/guards/admin.guard.ts`, `src/guards/distribution-center.guard.ts`. A user decorator provides authenticated identity to handlers at `src/decorators/UserDecorator/user.decorator.ts`.

#### Supply lifecycle and audit history
Supply changes are handled through the shelter-supply domain, then recorded as supply-history events. This is an explicit cross-cutting workflow implemented by a registration decorator and interceptor rather than only direct controller logic: `src/shelter-supply/shelter-supply.service.ts`, `src/supplies-history/supplies-history.service.ts`, `src/decorators/RegisterShelterSupplyHistory/RegisterShelterSupplyHistory.decorator.ts`, `src/interceptors/interceptors/shelter-supply-history/shelter-supply-history.interceptor.ts`. Donation orders form the upstream request/order flow: `src/donation-order/donation-order.service.ts`.

#### Persistence boundary
Prisma is the sole visible application persistence adapter, exposed as a Nest module/service and backed by PostgreSQL. The durable schema and evolution history are in `prisma/schema.prisma` and `prisma/migrations/`; user-specific persistence hooks reside in `src/prisma/hooks/user/user-hooks.ts`. Search-related schema support includes an `unaccent` migration at `prisma/migrations/20240517181431_add_unaccent_extension/migration.sql`.

#### Cross-cutting request handling
An HMAC decorator/guard supplies a separate request-integrity boundary where applied: `src/decorators/Hmac/hmac.decorator.ts`, `src/guards/hmac.guard.ts`. Response normalization and request logging are centralized, rather than duplicated across feature modules: `src/interceptors/interceptors/server-response/server-response.interceptor.ts`, `src/middlewares/logging.middleware.ts`.

#### Deployment and operations
The service is containerized for local and deployed environments with Docker Compose: `Dockerfile`, `docker-compose.yml`, `docker-compose.dev.yml`. Environment-specific secrets/configuration are supplied outside source via `.env.example`. GitHub Actions provides CI plus environment-oriented development, staging, and deploy workflows: `.github/workflows/ci.yml`, `.github/workflows/staging.yml`, `.github/workflows/deploy.yml`.

Main entry points: [`src/app.module.ts`](https://github.com/sos-rs/backend/blob/develop/src/app.module.ts) (Application composition), [`docs/endpoints.md`](https://github.com/sos-rs/backend/blob/develop/docs/endpoints.md) (REST controllers), [`src/prisma/hooks/user/user-hooks.ts`](https://github.com/sos-rs/backend/blob/develop/src/prisma/hooks/user/user-hooks.ts) (Prisma service), [`src/donation-order/donation-order.service.ts`](https://github.com/sos-rs/backend/blob/develop/src/donation-order/donation-order.service.ts) (Donation orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["API Runtime"]
  node_bootstrap{{"Nest bootstrap<br/>application entry<br/>[main.ts]"}}
  node_app_module["Application composition<br/>Nest module<br/>[app.module.ts]"]
  node_http_api["REST controllers<br/>HTTP boundary<br/>[endpoints.md]"]
  node_response_logging["Response and request handling<br/>interceptor middleware"]
end

subgraph group_domains["Domain Modules"]
  node_shelters["Shelters and search<br/>domain service<br/>[shelter.service.ts]"]
  node_supply_catalog["Supply catalog<br/>domain service<br/>[supply.service.ts]"]
  node_shelter_stock["Shelter supply stock<br/>domain service"]
  node_donation_orders["Donation orders<br/>domain service"]
  node_coordination["Partners and dashboard<br/>coordination service"]
  node_people["Users and participants<br/>domain services<br/>[users.service.ts]"]
end

subgraph group_security["Identity &amp; Request Policy"]
  node_sessions["JWT sessions<br/>authentication module<br/>[sessions.module.ts]"]
  node_route_guards["Role and scope guards<br/>authorization guards<br/>[admin.guard.ts]"]
  node_hmac["HMAC integrity guard<br/>request integrity<br/>[hmac.guard.ts]"]
end

subgraph group_data["Persistence &amp; Audit"]
  node_prisma[("Prisma service<br/>persistence adapter<br/>[user-hooks.ts]")]
  node_postgres[("PostgreSQL schema<br/>database<br/>[schema.prisma]")]
  node_supply_history["Supply history<br/>audit service"]
  node_history_interceptor["Supply audit interceptor<br/>cross-cutting interceptor"]
end

subgraph group_operations["Delivery &amp; Operations"]
  node_containers["Docker Compose deployment<br/>container orchestration<br/>[docker-compose.yml]"]
  node_ci_cd["GitHub Actions<br/>CI/CD workflows<br/>[ci.yml]"]
end

node_bootstrap -->|"starts"| node_app_module
node_app_module -->|"mounts"| node_http_api
node_app_module -->|"loads"| node_sessions
node_app_module -->|"loads"| node_shelters
node_app_module -->|"loads"| node_supply_catalog
node_app_module -->|"loads"| node_shelter_stock
node_app_module -->|"loads"| node_donation_orders
node_http_api -->|"passes through"| node_response_logging
node_http_api -->|"authenticates"| node_sessions
node_sessions -->|"provides identity"| node_route_guards
node_http_api -.->|"uses where decorated"| node_hmac
node_http_api -->|"routes requests"| node_shelters
node_http_api -->|"routes requests"| node_shelter_stock
node_http_api -->|"routes requests"| node_donation_orders
node_donation_orders -->|"coordinates distribution"| node_coordination
node_donation_orders -->|"drives supply flow"| node_shelter_stock
node_shelter_stock -->|"triggers"| node_history_interceptor
node_history_interceptor -->|"records event"| node_supply_history
node_shelters -->|"persists via"| node_prisma
node_supply_catalog -->|"persists via"| node_prisma
node_shelter_stock -->|"persists via"| node_prisma
node_donation_orders -->|"persists via"| node_prisma
node_people -->|"persists via"| node_prisma
node_supply_history -->|"persists via"| node_prisma
node_prisma -->|"reads and writes"| node_postgres
node_containers -->|"runs service"| node_bootstrap
node_ci_cd -->|"builds and deploys"| node_containers

click node_bootstrap "https://github.com/sos-rs/backend/blob/develop/src/main.ts"
click node_app_module "https://github.com/sos-rs/backend/blob/develop/src/app.module.ts"
click node_http_api "https://github.com/sos-rs/backend/blob/develop/docs/endpoints.md"
click node_response_logging "https://github.com/sos-rs/backend/blob/develop/src/interceptors/interceptors/server-response/server-response.interceptor.ts"
click node_shelters "https://github.com/sos-rs/backend/blob/develop/src/shelter/shelter.service.ts"
click node_supply_catalog "https://github.com/sos-rs/backend/blob/develop/src/supply/supply.service.ts"
click node_shelter_stock "https://github.com/sos-rs/backend/blob/develop/src/shelter-supply/shelter-supply.service.ts"
click node_donation_orders "https://github.com/sos-rs/backend/blob/develop/src/donation-order/donation-order.service.ts"
click node_coordination "https://github.com/sos-rs/backend/blob/develop/src/partners/partners.service.ts"
click node_people "https://github.com/sos-rs/backend/blob/develop/src/users/users.service.ts"
click node_sessions "https://github.com/sos-rs/backend/blob/develop/src/sessions/sessions.module.ts"
click node_route_guards "https://github.com/sos-rs/backend/blob/develop/src/guards/admin.guard.ts"
click node_hmac "https://github.com/sos-rs/backend/blob/develop/src/guards/hmac.guard.ts"
click node_prisma "https://github.com/sos-rs/backend/blob/develop/src/prisma/hooks/user/user-hooks.ts"
click node_postgres "https://github.com/sos-rs/backend/blob/develop/prisma/schema.prisma"
click node_supply_history "https://github.com/sos-rs/backend/blob/develop/src/supplies-history/supplies-history.service.ts"
click node_history_interceptor "https://github.com/sos-rs/backend/blob/develop/src/interceptors/interceptors/shelter-supply-history/shelter-supply-history.interceptor.ts"
click node_containers "https://github.com/sos-rs/backend/blob/develop/docker-compose.yml"
click node_ci_cd "https://github.com/sos-rs/backend/blob/develop/.github/workflows/ci.yml"

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_bootstrap,node_app_module,node_http_api,node_response_logging toneBlue
class node_shelters,node_supply_catalog,node_shelter_stock,node_donation_orders,node_coordination,node_people toneAmber
class node_sessions,node_route_guards,node_hmac toneMint
class node_prisma,node_postgres,node_supply_history,node_history_interceptor toneRose
class node_containers,node_ci_cd toneIndigo
```

## Components

### API Runtime

- [Nest bootstrap](https://github.com/sos-rs/backend/blob/develop/src/main.ts): application entry · `src/main.ts`
- [Application composition](https://github.com/sos-rs/backend/blob/develop/src/app.module.ts): Nest module · `src/app.module.ts`
- [REST controllers](https://github.com/sos-rs/backend/blob/develop/docs/endpoints.md): HTTP boundary · Endpoint contracts cover shelter and donation operations. · `docs/endpoints.md`
- [Response and request handling](https://github.com/sos-rs/backend/blob/develop/src/interceptors/interceptors/server-response/server-response.interceptor.ts): interceptor middleware · Centralizes response normalization and request logging. · `src/interceptors/interceptors/server-response/server-response.interceptor.ts`

### Domain Modules

- [Shelters and search](https://github.com/sos-rs/backend/blob/develop/src/shelter/shelter.service.ts): domain service · Manages shelters, capacities, pets, and search. · `src/shelter/shelter.service.ts`
- [Supply catalog](https://github.com/sos-rs/backend/blob/develop/src/supply/supply.service.ts): domain service · Catalog and category management. · `src/supply/supply.service.ts`
- [Shelter supply stock](https://github.com/sos-rs/backend/blob/develop/src/shelter-supply/shelter-supply.service.ts): domain service · Applies per-shelter inventory changes. · `src/shelter-supply/shelter-supply.service.ts`
- [Donation orders](https://github.com/sos-rs/backend/blob/develop/src/donation-order/donation-order.service.ts): domain service · Upstream donation request and ordering flow. · `src/donation-order/donation-order.service.ts`
- [Partners and dashboard](https://github.com/sos-rs/backend/blob/develop/src/partners/partners.service.ts): coordination service · Coordinates partners, distribution, and dashboard views. · `src/partners/partners.service.ts`
- [Users and participants](https://github.com/sos-rs/backend/blob/develop/src/users/users.service.ts): domain services · Users, shelter managers, and supporters. · `src/users/users.service.ts`

### Identity & Request Policy

- [JWT sessions](https://github.com/sos-rs/backend/blob/develop/src/sessions/sessions.module.ts): authentication module · Issues tokens and extracts authenticated identity. · `src/sessions/sessions.module.ts`
- [Role and scope guards](https://github.com/sos-rs/backend/blob/develop/src/guards/admin.guard.ts): authorization guards · Protects user, staff, admin, distribution-center, and applicant routes. · `src/guards/admin.guard.ts`
- [HMAC integrity guard](https://github.com/sos-rs/backend/blob/develop/src/guards/hmac.guard.ts): request integrity · Optional integrity boundary for decorated requests. · `src/guards/hmac.guard.ts`

### Persistence & Audit

- [Prisma service](https://github.com/sos-rs/backend/blob/develop/src/prisma/hooks/user/user-hooks.ts): persistence adapter · Sole application persistence adapter. · `src/prisma/hooks/user/user-hooks.ts`
- [PostgreSQL schema](https://github.com/sos-rs/backend/blob/develop/prisma/schema.prisma): database · Durable relational schema and migrations. · `prisma/schema.prisma`
- [Supply history](https://github.com/sos-rs/backend/blob/develop/src/supplies-history/supplies-history.service.ts): audit service · Records inventory-change events. · `src/supplies-history/supplies-history.service.ts`
- [Supply audit interceptor](https://github.com/sos-rs/backend/blob/develop/src/interceptors/interceptors/shelter-supply-history/shelter-supply-history.interceptor.ts): cross-cutting interceptor · Registers supply-history events around stock changes. · `src/interceptors/interceptors/shelter-supply-history/shelter-supply-history.interceptor.ts`

### Delivery & Operations

- [Docker Compose deployment](https://github.com/sos-rs/backend/blob/develop/docker-compose.yml): container orchestration · Local and deployed service environments. · `docker-compose.yml`
- [GitHub Actions](https://github.com/sos-rs/backend/blob/develop/.github/workflows/ci.yml): CI/CD workflows · CI, staging, and deployment automation. · `.github/workflows/ci.yml`

## Connections

- Nest bootstrap → Application composition: starts
- Application composition → REST controllers: mounts
- Application composition → JWT sessions: loads
- Application composition → Shelters and search: loads
- Application composition → Supply catalog: loads
- Application composition → Shelter supply stock: loads
- Application composition → Donation orders: loads
- REST controllers → Response and request handling: passes through
- REST controllers → JWT sessions: authenticates
- JWT sessions → Role and scope guards: provides identity
- REST controllers → HMAC integrity guard: uses where decorated
- REST controllers → Shelters and search: routes requests
- REST controllers → Shelter supply stock: routes requests
- REST controllers → Donation orders: routes requests
- Donation orders → Partners and dashboard: coordinates distribution
- Donation orders → Shelter supply stock: drives supply flow
- Shelter supply stock → Supply audit interceptor: triggers
- Supply audit interceptor → Supply history: records event
- Shelters and search → Prisma service: persists via
- Supply catalog → Prisma service: persists via
- Shelter supply stock → Prisma service: persists via
- Donation orders → Prisma service: persists via
- Users and participants → Prisma service: persists via
- Supply history → Prisma service: persists via
- Prisma service → PostgreSQL schema: reads and writes
- Docker Compose deployment → Nest bootstrap: runs service
- GitHub Actions → Docker Compose deployment: builds and deploys