# caiofugii/sanorte-vistorias-backend architecture

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

- Interactive diagram: https://gitdiagram.com/caiofugii/sanorte-vistorias-backend
- Repository: https://github.com/caiofugii/sanorte-vistorias-backend

## Overview

This is a NestJS REST backend for field inspections. Its main workflow authenticates users, lets authorized staff manage checklists and submit inspections, then handles evidence, signatures, finalization and pending-adjustment resolution; results also feed dashboards and exports. Other product areas cover operational records, reporting and asset uploads. The README documents the broader capabilities; sampled controllers and the SOURCE INDEX establish only some internal calls, so unsampled links are omitted rather than inferred.

Main entry points: [`src/storage/asset-storage.interface.ts`](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/asset-storage.interface.ts) (Asset storage), [`src/inspections/inspections.controller.ts`](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/inspections/inspections.controller.ts) (Inspection API), [`src/storage/adapters/s3-asset-storage.adapter.ts`](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/adapters/s3-asset-storage.adapter.ts) (S3 storage), [`src/storage/adapters/cloudinary-asset-storage.adapter.ts`](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/adapters/cloudinary-asset-storage.adapter.ts) (Cloudinary storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access &amp; setup"]
  node_auth["JWT authentication<br/>[auth.service.ts]"]
  node_users["Users<br/>[users.service.ts]"]
  node_teams["Teams<br/>[teams.service.ts]"]
  node_sectors["Sectors<br/>[sectors.service.ts]"]
  node_collaborators["Collaborators"]
end

subgraph group_inspection["Inspection workflow"]
  node_checklists["Checklists"]
  node_inspection_api["Inspection API"]
  node_inspections["Inspection lifecycle"]
  node_inspection_domain["Inspection rules"]
  node_sync["Offline sync<br/>[sync.controller.ts]"]
end

subgraph group_operations["Operational records"]
  node_contracts["Contracts"]
  node_service_orders["Service orders"]
  node_investment_works["Investment works"]
end

subgraph group_insights["Analytics &amp; reporting"]
  node_dashboards["Dashboards"]
  node_reports["Reports<br/>[reports.service.ts]"]
  node_excel["Excel exports<br/>[excel.service.ts]"]
end

subgraph group_assets["Files &amp; storage"]
  node_uploads["Upload API"]
  node_asset_storage["Asset storage"]
  node_storage_registry["Storage provider selection"]
  node_local_storage["Local storage"]
  node_s3_storage["S3 storage"]
  node_cloudinary_storage["Cloudinary storage"]
end

node_client(("API client"))
node_postgres[("PostgreSQL")]
node_s3["AWS S3"]
node_cloudinary["Cloudinary"]

node_client -->|"logs in"| node_auth
node_client -->|"submits inspections"| node_inspection_api
node_inspection_api -->|"dispatches lifecycle actions"| node_inspections
node_client -->|"manages checklists"| node_checklists
node_client -->|"syncs offline inspections"| node_sync
node_client -->|"requests metrics"| node_dashboards
node_client -->|"uploads assets"| node_uploads
node_client -->|"manages service orders"| node_service_orders
node_client -.->|"manages contracts"| node_contracts
node_client -.->|"manages work"| node_investment_works
node_client -.->|"requests reports"| node_reports
node_client -->|"manages users"| node_users
node_client -->|"manages teams"| node_teams
node_client -->|"manages sectors"| node_sectors
node_client -->|"manages collaborators"| node_collaborators
node_client -->|"downloads exports"| node_excel
node_inspection_api -->|"attaches export"| node_excel
node_client -->|"reads and writes records"| node_postgres
node_uploads -->|"uses storage interface"| node_asset_storage
node_checklists -->|"uses storage interface"| node_asset_storage
node_asset_storage -->|"selects provider"| node_storage_registry
node_local_storage -->|"implements interface"| node_asset_storage
node_s3_storage -->|"implements interface"| node_asset_storage
node_cloudinary_storage -.->|"migrates assets"| node_s3
node_s3_storage -->|"stores assets"| node_s3
node_cloudinary_storage -->|"stores assets"| node_cloudinary

click node_auth "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/auth/auth.service.ts"
click node_users "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/users/users.service.ts"
click node_teams "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/teams/teams.service.ts"
click node_sectors "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/sectors/sectors.service.ts"
click node_collaborators "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/collaborators/collaborators.service.ts"
click node_checklists "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/checklists/checklists.service.ts"
click node_inspection_api "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/inspections/inspections.controller.ts"
click node_inspections "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/inspections/inspections.service.ts"
click node_inspection_domain "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/inspections/inspection-domain.service.ts"
click node_sync "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/inspections/sync.controller.ts"
click node_contracts "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/contracts/contracts.service.ts"
click node_service_orders "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/service-orders/service-orders.service.ts"
click node_investment_works "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/investment-works/investment-works.service.ts"
click node_dashboards "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/dashboards/dashboards.service.ts"
click node_reports "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/reports/reports.service.ts"
click node_excel "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/excel/excel.service.ts"
click node_uploads "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/uploads/uploads.controller.ts"
click node_asset_storage "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/asset-storage.interface.ts"
click node_storage_registry "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/asset-storage.registry.ts"
click node_local_storage "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/adapters/local-asset-storage.adapter.ts"
click node_s3_storage "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/adapters/s3-asset-storage.adapter.ts"
click node_cloudinary_storage "https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/adapters/cloudinary-asset-storage.adapter.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_auth,node_users,node_teams,node_sectors,node_collaborators,node_client toneBlue
class node_checklists,node_inspection_api,node_inspections,node_inspection_domain,node_sync,node_postgres toneAmber
class node_contracts,node_service_orders,node_investment_works toneMint
class node_dashboards,node_reports,node_excel toneRose
class node_uploads,node_asset_storage,node_storage_registry,node_local_storage,node_s3_storage,node_cloudinary_storage,node_s3,node_cloudinary toneIndigo
```

## Components

### Access & setup

- [JWT authentication](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/auth/auth.service.ts): `src/auth/auth.service.ts`
- [Users](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/users/users.service.ts): `src/users/users.service.ts`
- [Teams](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/teams/teams.service.ts): `src/teams/teams.service.ts`
- [Sectors](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/sectors/sectors.service.ts): `src/sectors/sectors.service.ts`
- [Collaborators](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/collaborators/collaborators.service.ts): `src/collaborators/collaborators.service.ts`

### Inspection workflow

- [Checklists](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/checklists/checklists.service.ts): `src/checklists/checklists.service.ts`
- [Inspection API](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/inspections/inspections.controller.ts): `src/inspections/inspections.controller.ts`
- [Inspection lifecycle](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/inspections/inspections.service.ts): `src/inspections/inspections.service.ts`
- [Inspection rules](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/inspections/inspection-domain.service.ts): `src/inspections/inspection-domain.service.ts`
- [Offline sync](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/inspections/sync.controller.ts): `src/inspections/sync.controller.ts`

### Operational records

- [Contracts](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/contracts/contracts.service.ts): `src/contracts/contracts.service.ts`
- [Service orders](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/service-orders/service-orders.service.ts): `src/service-orders/service-orders.service.ts`
- [Investment works](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/investment-works/investment-works.service.ts): `src/investment-works/investment-works.service.ts`

### Analytics & reporting

- [Dashboards](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/dashboards/dashboards.service.ts): `src/dashboards/dashboards.service.ts`
- [Reports](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/reports/reports.service.ts): `src/reports/reports.service.ts`
- [Excel exports](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/excel/excel.service.ts): `src/excel/excel.service.ts`

### Files & storage

- [Upload API](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/uploads/uploads.controller.ts): `src/uploads/uploads.controller.ts`
- [Asset storage](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/asset-storage.interface.ts): `src/storage/asset-storage.interface.ts`
- [Storage provider selection](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/asset-storage.registry.ts): `src/storage/asset-storage.registry.ts`
- [Local storage](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/adapters/local-asset-storage.adapter.ts): `src/storage/adapters/local-asset-storage.adapter.ts`
- [S3 storage](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/adapters/s3-asset-storage.adapter.ts): `src/storage/adapters/s3-asset-storage.adapter.ts`
- [Cloudinary storage](https://github.com/caiofugii/sanorte-vistorias-backend/blob/main/src/storage/adapters/cloudinary-asset-storage.adapter.ts): `src/storage/adapters/cloudinary-asset-storage.adapter.ts`

### Other components

- **API client**
- **PostgreSQL**
- **AWS S3**
- **Cloudinary**

## Connections

- API client → JWT authentication: logs in
- API client → Inspection API: submits inspections
- Inspection API → Inspection lifecycle: dispatches lifecycle actions (evidence: `src/inspections/inspections.controller.ts`)
- API client → Checklists: manages checklists
- API client → Offline sync: syncs offline inspections
- API client → Dashboards: requests metrics
- API client → Upload API: uploads assets
- API client → Service orders: manages service orders
- API client → Contracts: manages contracts
- API client → Investment works: manages work
- API client → Reports: requests reports
- API client → Users: manages users
- API client → Teams: manages teams
- API client → Sectors: manages sectors
- API client → Collaborators: manages collaborators
- API client → Excel exports: downloads exports
- Inspection API → Excel exports: attaches export (evidence: `src/inspections/inspections.controller.ts`)
- API client → PostgreSQL: reads and writes records
- Upload API → Asset storage: uses storage interface (evidence: `src/uploads/uploads.controller.ts`)
- Checklists → Asset storage: uses storage interface (evidence: `src/checklists/checklists.service.ts`)
- Asset storage → Storage provider selection: selects provider (evidence: `src/checklists/checklists.service.ts`)
- Local storage → Asset storage: implements interface (evidence: `src/storage/adapters/local-asset-storage.adapter.ts`)
- S3 storage → Asset storage: implements interface (evidence: `src/storage/adapters/s3-asset-storage.adapter.ts`)
- Cloudinary storage → AWS S3: migrates assets
- S3 storage → AWS S3: stores assets
- Cloudinary storage → Cloudinary: stores assets
