How sos-rs/backend works
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: app.module.ts Application composition · endpoints.md REST controllers · user-hooks.ts Prisma service · donation-order.service.ts Donation orders
Components 19
API Runtime
- Nest bootstrap
src/main.ts - Application composition
src/app.module.ts - REST controllers · Endpoint contracts cover shelter and donation operations.
docs/endpoints.md - Response and request handling · Centralizes response normalization and request logging.
src/interceptors/interceptors/server-response/server-response.interceptor.ts
Domain Modules
- Shelters and search · Manages shelters, capacities, pets, and search.
src/shelter/shelter.service.ts - Supply catalog · Catalog and category management.
src/supply/supply.service.ts - Shelter supply stock · Applies per-shelter inventory changes.
src/shelter-supply/shelter-supply.service.ts - Donation orders · Upstream donation request and ordering flow.
src/donation-order/donation-order.service.ts - Partners and dashboard · Coordinates partners, distribution, and dashboard views.
src/partners/partners.service.ts - Users and participants · Users, shelter managers, and supporters.
src/users/users.service.ts
Identity & Request Policy
- JWT sessions · Issues tokens and extracts authenticated identity.
src/sessions/sessions.module.ts - Role and scope guards · Protects user, staff, admin, distribution-center, and applicant routes.
src/guards/admin.guard.ts - HMAC integrity guard · Optional integrity boundary for decorated requests.
src/guards/hmac.guard.ts
Persistence & Audit
- Prisma service · Sole application persistence adapter.
src/prisma/hooks/user/user-hooks.ts - PostgreSQL schema · Durable relational schema and migrations.
prisma/schema.prisma - Supply history · Records inventory-change events.
src/supplies-history/supplies-history.service.ts - Supply audit interceptor · Registers supply-history events around stock changes.
src/interceptors/interceptors/shelter-supply-history/shelter-supply-history.interceptor.ts
Delivery & Operations
- Docker Compose deployment · Local and deployed service environments.
docker-compose.yml - GitHub Actions · CI, staging, and deployment automation.
.github/workflows/ci.yml
Connections 27
- 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