# fruit-vale/backend architecture

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

- Interactive diagram: https://gitdiagram.com/fruit-vale/backend
- Repository: https://github.com/fruit-vale/backend

## Overview

FruitVale API serves a multi-company fruit-farming platform. Authenticated clients manage companies, properties, plots and crop seasons; IoT sensors publish measurements that are ingested, stored and used for alerts and dashboard views. Other documented product areas include forecasts, market information and export contracts. The graph emphasizes relationships visible in excerpts, the SOURCE INDEX, or the README; unsampled subsystems are included where documented, but their internal connections are not inferred.

Main entry points: [`src/prisma/prisma.service.ts`](https://github.com/fruit-vale/backend/blob/main/src/prisma/prisma.service.ts) (PostgreSQL), [`src/leituras/ingestao.service.ts`](https://github.com/fruit-vale/backend/blob/main/src/leituras/ingestao.service.ts) (Reading ingestion), [`src/sensores/sensores.service.ts`](https://github.com/fruit-vale/backend/blob/main/src/sensores/sensores.service.ts) (Sensor management), [`src/mqtt/dynsec.service.ts`](https://github.com/fruit-vale/backend/blob/main/src/mqtt/dynsec.service.ts) (MQTT Dynamic Security)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access &amp; tenants"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_scope["Data scope<br/>[escopo.ts]"]
  node_users["User management"]
  node_companies["Company management"]
end

subgraph group_farm["Farm operations"]
  node_properties["Properties"]
  node_plots["Plots &amp; geometry<br/>[lotes.service.ts]"]
  node_seasons["Crop seasons<br/>[safras.service.ts]"]
  node_cultures["Cultures"]
end

subgraph group_iot["IoT &amp; monitoring"]
  node_sensors["Sensor management"]
  node_mqttadmin["Broker administration"]
  node_dynsec["MQTT Dynamic Security<br/>[dynsec.service.ts]"]
  node_ingestion["Reading ingestion"]
  node_alerts["Measurement alerts<br/>[alertas.service.ts]"]
end

subgraph group_insights["Decision support"]
  node_dashboard["Dashboard &amp; readings<br/>[painel.service.ts]"]
  node_forecast["Harvest forecast"]
  node_market["Market information<br/>[mercado.service.ts]"]
  node_marketimport["Market import"]
  node_contracts["Export contracts"]
end

subgraph group_platform["Platform services"]
  node_email["Email delivery<br/>[email.service.ts]"]
  node_database[("PostgreSQL<br/>[prisma.service.ts]")]
  node_cache[("Redis cache<br/>[redis.service.ts]")]
end

node_client(("Frontend client"))
node_broker["Mosquitto broker"]

node_client -->|"logs in"| node_auth
node_client -->|"manages users"| node_users
node_client -->|"manages companies"| node_companies
node_auth -->|"reads users"| node_database
node_users -->|"reads and writes"| node_database
node_companies -->|"reads and writes"| node_database
node_client -->|"manages properties"| node_properties
node_client -->|"manages plots"| node_plots
node_plots -->|"routes season actions"| node_seasons
node_seasons -->|"uses plot service"| node_plots
node_client -->|"manages cultures"| node_cultures
node_client -->|"manages sensors"| node_sensors
node_client -->|"administers devices"| node_mqttadmin
node_mqttadmin -->|"delegates broker access"| node_dynsec
node_dynsec -->|"publishes commands"| node_broker
node_broker -->|"delivers readings"| node_ingestion
node_ingestion -->|"subscribes to topics"| node_dynsec
node_ingestion -->|"stores readings"| node_database
node_ingestion -->|"caches sensor lookup"| node_cache
node_client -->|"views alerts"| node_alerts
node_client -->|"views readings"| node_dashboard
node_client -->|"requests forecasts"| node_forecast
node_client -->|"views market data"| node_market
node_market -->|"uses import service"| node_marketimport
node_client -->|"manages contracts"| node_contracts
node_contracts -->|"reads and writes"| node_database
node_contracts -->|"sends contract email"| node_email
node_properties -->|"reads and writes"| node_database
node_cultures -->|"reads and writes"| node_database
node_sensors -->|"reads and writes"| node_database
node_sensors -->|"uses ingestion service"| node_ingestion
node_sensors -->|"uses broker security"| node_dynsec
node_market -->|"reads market data"| node_database
node_forecast -->|"reads farm data"| node_database
node_dashboard -->|"reads dashboard data"| node_database

click node_auth "https://github.com/fruit-vale/backend/blob/main/src/auth/auth.service.ts"
click node_scope "https://github.com/fruit-vale/backend/blob/main/src/auth/escopo.ts"
click node_users "https://github.com/fruit-vale/backend/blob/main/src/usuarios/usuarios.service.ts"
click node_companies "https://github.com/fruit-vale/backend/blob/main/src/empresas/empresas.service.ts"
click node_properties "https://github.com/fruit-vale/backend/blob/main/src/propriedades/propriedades.service.ts"
click node_plots "https://github.com/fruit-vale/backend/blob/main/src/lotes/lotes.service.ts"
click node_seasons "https://github.com/fruit-vale/backend/blob/main/src/lotes/safras.service.ts"
click node_cultures "https://github.com/fruit-vale/backend/blob/main/src/culturas/culturas.service.ts"
click node_sensors "https://github.com/fruit-vale/backend/blob/main/src/sensores/sensores.service.ts"
click node_mqttadmin "https://github.com/fruit-vale/backend/blob/main/src/mqtt/dispositivos.service.ts"
click node_dynsec "https://github.com/fruit-vale/backend/blob/main/src/mqtt/dynsec.service.ts"
click node_ingestion "https://github.com/fruit-vale/backend/blob/main/src/leituras/ingestao.service.ts"
click node_alerts "https://github.com/fruit-vale/backend/blob/main/src/alertas/alertas.service.ts"
click node_dashboard "https://github.com/fruit-vale/backend/blob/main/src/painel/painel.service.ts"
click node_forecast "https://github.com/fruit-vale/backend/blob/main/src/previsao/previsao.service.ts"
click node_market "https://github.com/fruit-vale/backend/blob/main/src/mercado/mercado.service.ts"
click node_marketimport "https://github.com/fruit-vale/backend/blob/main/src/mercado/mercado-importacao.service.ts"
click node_contracts "https://github.com/fruit-vale/backend/blob/main/src/contrato/contrato.service.ts"
click node_email "https://github.com/fruit-vale/backend/blob/main/src/email/email.service.ts"
click node_database "https://github.com/fruit-vale/backend/blob/main/src/prisma/prisma.service.ts"
click node_cache "https://github.com/fruit-vale/backend/blob/main/src/redis/redis.service.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_scope,node_users,node_companies,node_client toneBlue
class node_properties,node_plots,node_seasons,node_cultures toneAmber
class node_sensors,node_mqttadmin,node_dynsec,node_ingestion,node_alerts toneMint
class node_dashboard,node_forecast,node_market,node_marketimport,node_contracts toneRose
class node_email,node_database,node_cache,node_broker toneIndigo
```

## Components

### Access & tenants

- [Authentication](https://github.com/fruit-vale/backend/blob/main/src/auth/auth.service.ts): `src/auth/auth.service.ts`
- [Data scope](https://github.com/fruit-vale/backend/blob/main/src/auth/escopo.ts): `src/auth/escopo.ts`
- [User management](https://github.com/fruit-vale/backend/blob/main/src/usuarios/usuarios.service.ts): `src/usuarios/usuarios.service.ts`
- [Company management](https://github.com/fruit-vale/backend/blob/main/src/empresas/empresas.service.ts): `src/empresas/empresas.service.ts`

### Farm operations

- [Properties](https://github.com/fruit-vale/backend/blob/main/src/propriedades/propriedades.service.ts): `src/propriedades/propriedades.service.ts`
- [Plots & geometry](https://github.com/fruit-vale/backend/blob/main/src/lotes/lotes.service.ts): `src/lotes/lotes.service.ts`
- [Crop seasons](https://github.com/fruit-vale/backend/blob/main/src/lotes/safras.service.ts): `src/lotes/safras.service.ts`
- [Cultures](https://github.com/fruit-vale/backend/blob/main/src/culturas/culturas.service.ts): `src/culturas/culturas.service.ts`

### IoT & monitoring

- [Sensor management](https://github.com/fruit-vale/backend/blob/main/src/sensores/sensores.service.ts): `src/sensores/sensores.service.ts`
- [Broker administration](https://github.com/fruit-vale/backend/blob/main/src/mqtt/dispositivos.service.ts): `src/mqtt/dispositivos.service.ts`
- [MQTT Dynamic Security](https://github.com/fruit-vale/backend/blob/main/src/mqtt/dynsec.service.ts): `src/mqtt/dynsec.service.ts`
- [Reading ingestion](https://github.com/fruit-vale/backend/blob/main/src/leituras/ingestao.service.ts): `src/leituras/ingestao.service.ts`
- [Measurement alerts](https://github.com/fruit-vale/backend/blob/main/src/alertas/alertas.service.ts): `src/alertas/alertas.service.ts`

### Decision support

- [Dashboard & readings](https://github.com/fruit-vale/backend/blob/main/src/painel/painel.service.ts): `src/painel/painel.service.ts`
- [Harvest forecast](https://github.com/fruit-vale/backend/blob/main/src/previsao/previsao.service.ts): `src/previsao/previsao.service.ts`
- [Market information](https://github.com/fruit-vale/backend/blob/main/src/mercado/mercado.service.ts): `src/mercado/mercado.service.ts`
- [Market import](https://github.com/fruit-vale/backend/blob/main/src/mercado/mercado-importacao.service.ts): `src/mercado/mercado-importacao.service.ts`
- [Export contracts](https://github.com/fruit-vale/backend/blob/main/src/contrato/contrato.service.ts): `src/contrato/contrato.service.ts`

### Platform services

- [Email delivery](https://github.com/fruit-vale/backend/blob/main/src/email/email.service.ts): `src/email/email.service.ts`
- [PostgreSQL](https://github.com/fruit-vale/backend/blob/main/src/prisma/prisma.service.ts): `src/prisma/prisma.service.ts`
- [Redis cache](https://github.com/fruit-vale/backend/blob/main/src/redis/redis.service.ts): `src/redis/redis.service.ts`

### Other components

- **Frontend client**
- **Mosquitto broker**

## Connections

- Frontend client → Authentication: logs in
- Frontend client → User management: manages users
- Frontend client → Company management: manages companies
- Authentication → PostgreSQL: reads users (evidence: `src/auth/auth.service.ts`)
- User management → PostgreSQL: reads and writes (evidence: `src/usuarios/usuarios.service.ts`)
- Company management → PostgreSQL: reads and writes (evidence: `src/empresas/empresas.service.ts`)
- Frontend client → Properties: manages properties
- Frontend client → Plots & geometry: manages plots
- Plots & geometry → Crop seasons: routes season actions (evidence: `src/lotes/lotes.controller.ts`)
- Crop seasons → Plots & geometry: uses plot service (evidence: `src/lotes/safras.service.ts`)
- Frontend client → Cultures: manages cultures
- Frontend client → Sensor management: manages sensors
- Frontend client → Broker administration: administers devices
- Broker administration → MQTT Dynamic Security: delegates broker access (evidence: `src/mqtt/mqtt.controller.ts`)
- MQTT Dynamic Security → Mosquitto broker: publishes commands (evidence: `src/mqtt/dynsec.service.ts`)
- Mosquitto broker → Reading ingestion: delivers readings (evidence: `src/leituras/ingestao.service.ts`)
- Reading ingestion → MQTT Dynamic Security: subscribes to topics (evidence: `src/leituras/ingestao.service.ts`)
- Reading ingestion → PostgreSQL: stores readings (evidence: `src/leituras/ingestao.service.ts`)
- Reading ingestion → Redis cache: caches sensor lookup (evidence: `src/leituras/ingestao.service.ts`)
- Frontend client → Measurement alerts: views alerts
- Frontend client → Dashboard & readings: views readings
- Frontend client → Harvest forecast: requests forecasts
- Frontend client → Market information: views market data
- Market information → Market import: uses import service (evidence: `src/mercado/mercado.service.ts`)
- Frontend client → Export contracts: manages contracts
- Export contracts → PostgreSQL: reads and writes (evidence: `src/contrato/contrato.service.ts`)
- Export contracts → Email delivery: sends contract email (evidence: `src/contrato/contrato.service.ts`)
- Properties → PostgreSQL: reads and writes (evidence: `src/propriedades/propriedades.service.ts`)
- Cultures → PostgreSQL: reads and writes (evidence: `src/culturas/culturas.service.ts`)
- Sensor management → PostgreSQL: reads and writes (evidence: `src/sensores/sensores.service.ts`)
- Sensor management → Reading ingestion: uses ingestion service (evidence: `src/sensores/sensores.service.ts`)
- Sensor management → MQTT Dynamic Security: uses broker security (evidence: `src/sensores/sensores.service.ts`)
- Market information → PostgreSQL: reads market data (evidence: `src/mercado/mercado.service.ts`)
- Harvest forecast → PostgreSQL: reads farm data (evidence: `src/previsao/previsao.service.ts`)
- Dashboard & readings → PostgreSQL: reads dashboard data (evidence: `src/painel/painel.service.ts`)
