# ricardoshuree/gasfavero architecture

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

- Interactive diagram: https://gitdiagram.com/ricardoshuree/gasfavero
- Repository: https://github.com/ricardoshuree/gasfavero

## Overview

Gasfavero is a gas-sales ERP with a separate driver app, backed by a FastAPI service and PostgreSQL/Supabase. Office users authenticate, use operational and administrative screens, and send requests to backend routes for sales, customers, finance, inventory-related work, mapping and access management. Drivers use a mobile workflow for demands and sales, plus finance and account tasks. The README documents closed-system local/Google authentication and RBAC. Route and persistence internals were not sampled, so domain-specific backend wiring is shown only at the supported router boundary.

Main entry points: [`backend/app/api/main.py`](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/main.py) (API router), [`backend/app/main.py`](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/main.py) (FastAPI app), [`frontend/src/routes`](https://github.com/ricardoshuree/gasfavero/tree/main/frontend/src/routes) (ERP screens), [`frontend/src/hooks/useAuth.ts`](https://github.com/ricardoshuree/gasfavero/blob/main/frontend/src/hooks/useAuth.ts) (Frontend auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_office["ERP frontend"]
  node_office_ui["ERP screens"]
  node_office_auth["Frontend auth<br/>[useAuth.ts]"]
  node_office_permissions["Permission UI<br/>[usePermissions.ts]"]
end

subgraph group_driver["Driver app"]
  node_driver_app["Driver workflow<br/>[App.tsx]"]
  node_driver_sales["Driver sales<br/>[VendasTela.tsx]"]
  node_driver_api["Driver API client<br/>[api.ts]"]
end

subgraph group_backend["Backend service"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_api_router["API router<br/>[main.py]"]
  node_auth_deps["Auth dependencies<br/>[deps.py]"]
  node_sales_routes["Sales operations<br/>[vendas.py]"]
  node_customer_routes["Customer operations<br/>[clientes.py]"]
  node_finance_routes["Finance operations<br/>[fechamento.py]"]
  node_rbac_routes["RBAC management<br/>[roles.py]"]
  node_other_routes["Other operations"]
end

subgraph group_state["Data and identity"]
  node_models["ERP models<br/>[models.py]"]
  node_db[("Database access<br/>[db.py]")]
  node_supabase_auth["Supabase auth<br/>[supabase.ts]"]
end

node_office_user(("Office user"))
node_driver_user(("Driver"))
node_postgres[("PostgreSQL")]
node_supabase["Supabase Auth"]

node_office_user -->|"uses"| node_office_ui
node_office_ui -->|"authenticates through"| node_office_auth
node_office_auth -->|"login requests"| node_api_app
node_office_auth -->|"starts OAuth"| node_supabase_auth
node_supabase_auth -->|"authenticates with"| node_supabase
node_office_ui -->|"API requests"| node_api_app
node_office_permissions -->|"permission requests"| node_api_app
node_api_app -->|"dispatches"| node_api_router
node_api_router -->|"includes auth routes"| node_auth_deps
node_api_router -->|"includes routes"| node_sales_routes
node_api_router -->|"includes routes"| node_customer_routes
node_api_router -->|"includes routes"| node_finance_routes
node_api_router -->|"includes routes"| node_rbac_routes
node_api_router -->|"includes routes"| node_other_routes
node_driver_user -->|"uses"| node_driver_app
node_driver_app -->|"opens sales"| node_driver_sales
node_driver_app -->|"uses"| node_driver_api
node_driver_api -->|"API requests"| node_api_app
node_db -->|"uses models"| node_models
node_db -->|"reads and writes"| node_postgres
node_api_router -->|"persists operational data"| node_db

click node_office_ui "https://github.com/ricardoshuree/gasfavero/tree/main/frontend/src/routes"
click node_office_auth "https://github.com/ricardoshuree/gasfavero/blob/main/frontend/src/hooks/useAuth.ts"
click node_office_permissions "https://github.com/ricardoshuree/gasfavero/blob/main/frontend/src/hooks/usePermissions.ts"
click node_driver_app "https://github.com/ricardoshuree/gasfavero/blob/main/frontend-motorista/src/App.tsx"
click node_driver_sales "https://github.com/ricardoshuree/gasfavero/blob/main/frontend-motorista/src/components/VendasTela.tsx"
click node_driver_api "https://github.com/ricardoshuree/gasfavero/blob/main/frontend-motorista/src/lib/api.ts"
click node_api_app "https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/main.py"
click node_api_router "https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/main.py"
click node_auth_deps "https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/deps.py"
click node_sales_routes "https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/routes/vendas.py"
click node_customer_routes "https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/routes/clientes.py"
click node_finance_routes "https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/routes/fechamento.py"
click node_rbac_routes "https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/routes/roles.py"
click node_other_routes "https://github.com/ricardoshuree/gasfavero/tree/main/backend/app/api/routes"
click node_models "https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/models.py"
click node_db "https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/core/db.py"
click node_supabase_auth "https://github.com/ricardoshuree/gasfavero/blob/main/frontend/src/lib/supabase.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_office_ui,node_office_auth,node_office_permissions,node_office_user toneBlue
class node_driver_app,node_driver_sales,node_driver_api,node_postgres toneAmber
class node_api_app,node_api_router,node_auth_deps,node_sales_routes,node_customer_routes,node_finance_routes,node_rbac_routes,node_other_routes toneMint
class node_models,node_db,node_supabase_auth toneRose
class node_driver_user,node_supabase toneIndigo
```

## Components

### ERP frontend

- [ERP screens](https://github.com/ricardoshuree/gasfavero/tree/main/frontend/src/routes): `frontend/src/routes`
- [Frontend auth](https://github.com/ricardoshuree/gasfavero/blob/main/frontend/src/hooks/useAuth.ts): `frontend/src/hooks/useAuth.ts`
- [Permission UI](https://github.com/ricardoshuree/gasfavero/blob/main/frontend/src/hooks/usePermissions.ts): `frontend/src/hooks/usePermissions.ts`

### Driver app

- [Driver workflow](https://github.com/ricardoshuree/gasfavero/blob/main/frontend-motorista/src/App.tsx): `frontend-motorista/src/App.tsx`
- [Driver sales](https://github.com/ricardoshuree/gasfavero/blob/main/frontend-motorista/src/components/VendasTela.tsx): `frontend-motorista/src/components/VendasTela.tsx`
- [Driver API client](https://github.com/ricardoshuree/gasfavero/blob/main/frontend-motorista/src/lib/api.ts): `frontend-motorista/src/lib/api.ts`

### Backend service

- [FastAPI app](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/main.py): `backend/app/api/main.py`
- [Auth dependencies](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [Sales operations](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/routes/vendas.py): `backend/app/api/routes/vendas.py`
- [Customer operations](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/routes/clientes.py): `backend/app/api/routes/clientes.py`
- [Finance operations](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/routes/fechamento.py): `backend/app/api/routes/fechamento.py`
- [RBAC management](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/api/routes/roles.py): `backend/app/api/routes/roles.py`
- [Other operations](https://github.com/ricardoshuree/gasfavero/tree/main/backend/app/api/routes): `backend/app/api/routes`

### Data and identity

- [ERP models](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/models.py): `backend/app/models.py`
- [Database access](https://github.com/ricardoshuree/gasfavero/blob/main/backend/app/core/db.py): `backend/app/core/db.py`
- [Supabase auth](https://github.com/ricardoshuree/gasfavero/blob/main/frontend/src/lib/supabase.ts): `frontend/src/lib/supabase.ts`

### Other components

- **Office user**
- **Driver**
- **PostgreSQL**
- **Supabase Auth**

## Connections

- Office user → ERP screens: uses
- ERP screens → Frontend auth: authenticates through
- Frontend auth → FastAPI app: login requests
- Frontend auth → Supabase auth: starts OAuth
- Supabase auth → Supabase Auth: authenticates with
- ERP screens → FastAPI app: API requests
- Permission UI → FastAPI app: permission requests
- FastAPI app → API router: dispatches
- API router → Auth dependencies: includes auth routes
- API router → Sales operations: includes routes
- API router → Customer operations: includes routes
- API router → Finance operations: includes routes
- API router → RBAC management: includes routes
- API router → Other operations: includes routes
- Driver → Driver workflow: uses
- Driver workflow → Driver sales: opens sales
- Driver workflow → Driver API client: uses
- Driver API client → FastAPI app: API requests
- Database access → ERP models: uses models
- Database access → PostgreSQL: reads and writes
- API router → Database access: persists operational data