# rs-talentos-ufsm/sulflux.backend architecture

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

- Interactive diagram: https://gitdiagram.com/rs-talentos-ufsm/sulflux.backend
- Repository: https://github.com/rs-talentos-ufsm/sulflux.backend

## Overview

This repository is a production-oriented Express backend template. A client sends API requests through the app’s global middleware and route dispatch; domain controllers validate requests, delegate to services, and return results backed by PostgreSQL. Authentication protects selected routes with cookie-based JWTs. The graph also preserves documented validation, API documentation, security, and observability capabilities. Some supporting source was not sampled, so unsourced wiring is omitted rather than inferred.

Main entry points: [`src/app.ts`](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/app.ts) (Express app), [`src/routes/index.ts`](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/routes/index.ts) (Route dispatch), [`src/middleware/ensureAuthenticated.ts`](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/middleware/ensureAuthenticated.ts) (JWT auth), [`src/infra/database.ts`](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/infra/database.ts) (Prisma data access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API entry"]
  node_app["Express app<br/>[app.ts]"]
  node_route_dispatch["Route dispatch<br/>[index.ts]"]
  node_auth_routes["Auth routes<br/>[auth.routes.ts]"]
  node_user_routes["User routes<br/>[user.routes.ts]"]
  node_property_routes["Property routes<br/>[property.routes.ts]"]
  node_field_routes["Field routes<br/>[field.routes.ts]"]
end

subgraph group_domain["Domain modules"]
  node_auth_controller["Auth controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_user_controller["User controller<br/>[user.controller.ts]"]
  node_user_service["User service<br/>[user.service.ts]"]
  node_property_controller["Property controller"]
  node_property_service["Property service"]
  node_field_controller["Field controller"]
  node_field_service["Field service<br/>[field.service.ts]"]
end

subgraph group_data["Data and security"]
  node_auth_middleware["JWT auth"]
  node_token_utils["JWT utilities<br/>[jwt.ts]"]
  node_password_utils["Password hashing"]
  node_database["Prisma data access<br/>[database.ts]"]
end

subgraph group_platform["Cross-cutting services"]
  node_validation["Payload validation"]
  node_security["HTTP protections<br/>[app.ts]"]
  node_swagger["Swagger docs<br/>[swagger.ts]"]
  node_logging["Structured logging<br/>[logger.ts]"]
  node_tracing["OpenTelemetry<br/>[tracing.ts]"]
  node_file_storage["File storage"]
end

node_client(("API client"))
node_postgres[("PostgreSQL")]

node_client -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_route_dispatch
node_route_dispatch -->|"dispatches auth"| node_auth_routes
node_route_dispatch -->|"dispatches users"| node_user_routes
node_route_dispatch -->|"dispatches properties"| node_property_routes
node_route_dispatch -->|"dispatches fields"| node_field_routes
node_auth_routes -->|"routes to"| node_auth_controller
node_user_routes -->|"routes to"| node_user_controller
node_property_routes -->|"routes to"| node_property_controller
node_field_routes -->|"routes to"| node_field_controller
node_auth_routes -->|"guards routes"| node_auth_middleware
node_user_routes -->|"guards routes"| node_auth_middleware
node_property_routes -->|"guards routes"| node_auth_middleware
node_field_routes -->|"guards routes"| node_auth_middleware
node_auth_controller -->|"delegates to"| node_auth_service
node_user_controller -->|"delegates to"| node_user_service
node_property_controller -->|"delegates to"| node_property_service
node_field_controller -->|"delegates to"| node_field_service
node_auth_middleware -->|"verifies token"| node_token_utils
node_auth_service -->|"reads and writes"| node_database
node_auth_service -->|"hashes passwords"| node_password_utils
node_auth_service -->|"issues tokens"| node_token_utils
node_user_service -->|"reads and writes"| node_database
node_property_service -->|"reads and writes"| node_database
node_field_service -->|"reads and writes"| node_database
node_database -->|"persists data"| node_postgres
node_app -->|"sets up docs"| node_swagger
node_app -->|"configures logging"| node_logging
node_app -->|"applies protections"| node_security
node_app -.->|"validates requests"| node_validation
node_app -.->|"starts tracing"| node_tracing

click node_app "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/app.ts"
click node_route_dispatch "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/routes/index.ts"
click node_auth_routes "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/auth/auth.routes.ts"
click node_user_routes "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/user/user.routes.ts"
click node_property_routes "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/property/property.routes.ts"
click node_field_routes "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/field/field.routes.ts"
click node_auth_controller "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/auth/auth.controller.ts"
click node_auth_service "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/auth/auth.service.ts"
click node_user_controller "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/user/user.controller.ts"
click node_user_service "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/user/user.service.ts"
click node_property_controller "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/property/property.controller.ts"
click node_property_service "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/property/property.service.ts"
click node_field_controller "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/field/field.controller.ts"
click node_field_service "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/field/field.service.ts"
click node_auth_middleware "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/middleware/ensureAuthenticated.ts"
click node_token_utils "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/utils/jwt.ts"
click node_password_utils "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/utils/password.service.ts"
click node_database "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/infra/database.ts"
click node_validation "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/middleware/validateMiddleware.ts"
click node_security "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/app.ts"
click node_swagger "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/utils/swagger.ts"
click node_logging "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/utils/logger.ts"
click node_tracing "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/observability/tracing.ts"
click node_file_storage "https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/utils/FileStorageService.ts"

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_app,node_route_dispatch,node_auth_routes,node_user_routes,node_property_routes,node_field_routes,node_client toneBlue
class node_auth_controller,node_auth_service,node_user_controller,node_user_service,node_property_controller,node_property_service,node_field_controller,node_field_service,node_postgres toneAmber
class node_auth_middleware,node_token_utils,node_password_utils,node_database toneMint
class node_validation,node_security,node_swagger,node_logging,node_tracing,node_file_storage toneRose
```

## Components

### API entry

- [Express app](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/app.ts): `src/app.ts`
- [Route dispatch](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/routes/index.ts): `src/routes/index.ts`
- [Auth routes](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/auth/auth.routes.ts): `src/modules/auth/auth.routes.ts`
- [User routes](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/user/user.routes.ts): `src/modules/user/user.routes.ts`
- [Property routes](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/property/property.routes.ts): `src/modules/property/property.routes.ts`
- [Field routes](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/field/field.routes.ts): `src/modules/field/field.routes.ts`

### Domain modules

- [Auth controller](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/auth/auth.controller.ts): `src/modules/auth/auth.controller.ts`
- [Auth service](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/auth/auth.service.ts): `src/modules/auth/auth.service.ts`
- [User controller](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/user/user.controller.ts): `src/modules/user/user.controller.ts`
- [User service](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/user/user.service.ts): `src/modules/user/user.service.ts`
- [Property controller](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/property/property.controller.ts): `src/modules/property/property.controller.ts`
- [Property service](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/property/property.service.ts): `src/modules/property/property.service.ts`
- [Field controller](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/field/field.controller.ts): `src/modules/field/field.controller.ts`
- [Field service](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/modules/field/field.service.ts): `src/modules/field/field.service.ts`

### Data and security

- [JWT auth](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/middleware/ensureAuthenticated.ts): `src/middleware/ensureAuthenticated.ts`
- [JWT utilities](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/utils/jwt.ts): `src/utils/jwt.ts`
- [Password hashing](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/utils/password.service.ts): `src/utils/password.service.ts`
- [Prisma data access](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/infra/database.ts): `src/infra/database.ts`

### Cross-cutting services

- [Payload validation](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/middleware/validateMiddleware.ts): `src/middleware/validateMiddleware.ts`
- [HTTP protections](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/app.ts): `src/app.ts`
- [Swagger docs](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/utils/swagger.ts): `src/utils/swagger.ts`
- [Structured logging](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/utils/logger.ts): `src/utils/logger.ts`
- [OpenTelemetry](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/observability/tracing.ts): `src/observability/tracing.ts`
- [File storage](https://github.com/rs-talentos-ufsm/sulflux.backend/blob/main/src/utils/FileStorageService.ts): `src/utils/FileStorageService.ts`

### Other components

- **API client**
- **PostgreSQL**

## Connections

- API client → Express app: sends requests (evidence: `src/app.ts`)
- Express app → Route dispatch: mounts routes (evidence: `src/app.ts`)
- Route dispatch → Auth routes: dispatches auth (evidence: `src/routes/index.ts`)
- Route dispatch → User routes: dispatches users (evidence: `src/routes/index.ts`)
- Route dispatch → Property routes: dispatches properties (evidence: `src/routes/index.ts`)
- Route dispatch → Field routes: dispatches fields (evidence: `src/routes/index.ts`)
- Auth routes → Auth controller: routes to (evidence: `src/modules/auth/auth.routes.ts`)
- User routes → User controller: routes to (evidence: `src/modules/user/user.routes.ts`)
- Property routes → Property controller: routes to (evidence: `src/modules/property/property.routes.ts`)
- Field routes → Field controller: routes to (evidence: `src/modules/field/field.routes.ts`)
- Auth routes → JWT auth: guards routes (evidence: `src/modules/auth/auth.routes.ts`)
- User routes → JWT auth: guards routes (evidence: `src/modules/user/user.routes.ts`)
- Property routes → JWT auth: guards routes (evidence: `src/modules/property/property.routes.ts`)
- Field routes → JWT auth: guards routes (evidence: `src/modules/field/field.routes.ts`)
- Auth controller → Auth service: delegates to (evidence: `src/modules/auth/auth.controller.ts`)
- User controller → User service: delegates to (evidence: `src/modules/user/user.controller.ts`)
- Property controller → Property service: delegates to (evidence: `src/modules/property/property.controller.ts`)
- Field controller → Field service: delegates to (evidence: `src/modules/field/field.controller.ts`)
- JWT auth → JWT utilities: verifies token (evidence: `src/middleware/ensureAuthenticated.ts`)
- Auth service → Prisma data access: reads and writes (evidence: `src/modules/auth/auth.service.ts`)
- Auth service → Password hashing: hashes passwords (evidence: `src/modules/auth/auth.service.ts`)
- Auth service → JWT utilities: issues tokens (evidence: `src/modules/auth/auth.service.ts`)
- User service → Prisma data access: reads and writes (evidence: `src/modules/user/user.service.ts`)
- Property service → Prisma data access: reads and writes (evidence: `src/modules/property/property.service.ts`)
- Field service → Prisma data access: reads and writes (evidence: `src/modules/field/field.service.ts`)
- Prisma data access → PostgreSQL: persists data (evidence: `README.md`)
- Express app → Swagger docs: sets up docs (evidence: `src/app.ts`)
- Express app → Structured logging: configures logging (evidence: `src/app.ts`)
- Express app → HTTP protections: applies protections (evidence: `src/app.ts`)
- Express app → Payload validation: validates requests (evidence: `README.md`)
- Express app → OpenTelemetry: starts tracing (evidence: `src/server.ts`)
