# kainonsolucoes1-beep/o2-solution architecture

> Architecture diagram of the GitHub repository kainonsolucoes1-beep/o2-solution, 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/kainonsolucoes1-beep/o2-solution
- Repository: https://github.com/kainonsolucoes1-beep/o2-solution

## Overview

O2 Solution is a lead-management SaaS: users sign in, work leads through pipeline and campaign processes, and review operational and financial results. Its React application calls a FastAPI backend that applies role/team visibility rules and reads or writes PostgreSQL. The backend also syncs leads from Followize; the README documents a 30-minute sync cadence. The graph preserves documented product areas, but several route implementations and frontend pages were not excerpted, so some subsystem links are shown only where the index or README supports them.

Main entry points: [`frontend/src/App.tsx`](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/App.tsx) (Application routes), [`backend/app/main.py`](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/main.py) (API application), [`frontend/src/api/index.ts`](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/api/index.ts) (API client), [`backend/app/api/leads_routes.py`](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/leads_routes.py) (Lead operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Application routes<br/>[App.tsx]"]
  node_api_client["API client<br/>[index.ts]"]
  node_theme["Theme state<br/>[ThemeContext.tsx]"]
end

subgraph group_sales["Lead operations"]
  node_lead_ui["Lead workspace<br/>[LeadDetailPage.tsx]"]
  node_pipeline_ui["Pipeline view<br/>[Pipeline.tsx]"]
  node_campaign_ui["Campaign tools<br/>[CampanhasFila.tsx]"]
  node_lead_api["Lead operations<br/>[leads_routes.py]"]
  node_pipeline_api["Pipeline service<br/>[pipeline_routes.py]"]
  node_campaign_api["Campaign service"]
end

subgraph group_insights["Analytics and finance"]
  node_dashboard_ui["Dashboard<br/>[Dashboard.tsx]"]
  node_commercial_ui["Commercial analytics"]
  node_kpi_ui["KPI reporting<br/>[KPIs.tsx]"]
  node_finance_ui["Finance workspace<br/>[Financeiro.tsx]"]
  node_dashboard_api["Dashboard metrics"]
  node_commercial_api["Commercial metrics"]
  node_kpi_api["KPI service<br/>[kpis_routes.py]"]
  node_finance_api["Finance services"]
  node_emission["Emissions<br/>[emissao_routes.py]"]
end

subgraph group_platform["Backend platform"]
  node_backend_app["API application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth_routes.py]"]
  node_security["Access policy<br/>[security.py]"]
  node_lead_utils["Lead rules<br/>[lead_utils.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_integrations["External integrations"]
  node_sync["Followize sync<br/>[sync_followize.py]"]
  node_sheets["Revenue sheets<br/>[sheets_receita.py]"]
  node_storage["Attachment storage<br/>[storage_r2.py]"]
end

node_users(("Business users"))
node_followize["Followize"]
node_r2["Cloud object storage"]

node_users -->|"use"| node_app
node_app -->|"routes to"| node_lead_ui
node_app -->|"routes to"| node_pipeline_ui
node_app -->|"routes to"| node_campaign_ui
node_app -->|"routes to"| node_dashboard_ui
node_app -->|"routes to"| node_commercial_ui
node_app -->|"routes to"| node_kpi_ui
node_app -->|"routes to"| node_finance_ui
node_app -->|"provides theme"| node_theme
node_lead_ui -->|"requests data"| node_api_client
node_pipeline_ui -->|"requests data"| node_api_client
node_campaign_ui -.->|"requests data"| node_api_client
node_dashboard_ui -.->|"requests data"| node_api_client
node_commercial_ui -->|"requests data"| node_api_client
node_kpi_ui -->|"requests data"| node_api_client
node_finance_ui -.->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_backend_app
node_backend_app -->|"registers routes"| node_auth
node_backend_app -->|"registers routes"| node_lead_api
node_backend_app -->|"registers routes"| node_pipeline_api
node_backend_app -->|"registers routes"| node_campaign_api
node_backend_app -->|"registers routes"| node_dashboard_api
node_backend_app -->|"registers routes"| node_commercial_api
node_backend_app -->|"registers routes"| node_kpi_api
node_auth -->|"checks access"| node_security
node_auth -->|"reads users"| node_postgres
node_lead_api -->|"reads and writes"| node_postgres
node_lead_api -->|"uses rules"| node_lead_utils
node_pipeline_api -->|"queries leads"| node_postgres
node_campaign_api -->|"queries leads"| node_postgres
node_dashboard_api -->|"queries metrics"| node_postgres
node_commercial_api -->|"queries metrics"| node_postgres
node_commercial_api -->|"uses rules"| node_lead_utils
node_kpi_api -->|"queries metrics"| node_postgres
node_finance_api -.->|"reads and writes"| node_postgres
node_emission -.->|"reads and writes"| node_postgres
node_sync -->|"syncs leads"| node_followize
node_sync -->|"updates leads"| node_postgres
node_sheets -->|"syncs revenue"| node_postgres
node_lead_api -->|"handles attachments"| node_storage
node_storage -.->|"stores files"| node_r2

click node_app "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/api/index.ts"
click node_theme "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/ThemeContext.tsx"
click node_lead_ui "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/LeadDetailPage.tsx"
click node_pipeline_ui "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/Pipeline.tsx"
click node_campaign_ui "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/CampanhasFila.tsx"
click node_lead_api "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/leads_routes.py"
click node_pipeline_api "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/pipeline_routes.py"
click node_campaign_api "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/campanhas_routes.py"
click node_dashboard_ui "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/Dashboard.tsx"
click node_commercial_ui "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/GestaoComercial.tsx"
click node_kpi_ui "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/KPIs.tsx"
click node_finance_ui "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/Financeiro.tsx"
click node_dashboard_api "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/dashboard_routes.py"
click node_commercial_api "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/gestao_comercial_routes.py"
click node_kpi_api "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/kpis_routes.py"
click node_finance_api "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/financeiro_routes.py"
click node_emission "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/emissao_routes.py"
click node_backend_app "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/main.py"
click node_auth "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/auth_routes.py"
click node_security "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/security.py"
click node_lead_utils "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/lead_utils.py"
click node_sync "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/sync_followize.py"
click node_sheets "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/sheets_receita.py"
click node_storage "https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/storage_r2.py"

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_api_client,node_theme,node_users toneBlue
class node_lead_ui,node_pipeline_ui,node_campaign_ui,node_lead_api,node_pipeline_api,node_campaign_api,node_r2 toneAmber
class node_dashboard_ui,node_commercial_ui,node_kpi_ui,node_finance_ui,node_dashboard_api,node_commercial_api,node_kpi_api,node_finance_api,node_emission toneMint
class node_backend_app,node_auth,node_security,node_lead_utils,node_postgres toneRose
class node_sync,node_sheets,node_storage,node_followize toneIndigo
```

## Components

### User experience

- [Application routes](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/api/index.ts): `frontend/src/api/index.ts`
- [Theme state](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/ThemeContext.tsx): `frontend/src/ThemeContext.tsx`

### Lead operations

- [Lead workspace](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/LeadDetailPage.tsx): `frontend/src/pages/LeadDetailPage.tsx`
- [Pipeline view](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/Pipeline.tsx): `frontend/src/pages/Pipeline.tsx`
- [Campaign tools](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/CampanhasFila.tsx): `frontend/src/pages/CampanhasFila.tsx`
- [Lead operations](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/leads_routes.py): `backend/app/api/leads_routes.py`
- [Pipeline service](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/pipeline_routes.py): `backend/app/api/pipeline_routes.py`
- [Campaign service](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/campanhas_routes.py): `backend/app/api/campanhas_routes.py`

### Analytics and finance

- [Dashboard](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Commercial analytics](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/GestaoComercial.tsx): `frontend/src/pages/GestaoComercial.tsx`
- [KPI reporting](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/KPIs.tsx): `frontend/src/pages/KPIs.tsx`
- [Finance workspace](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/frontend/src/pages/Financeiro.tsx): `frontend/src/pages/Financeiro.tsx`
- [Dashboard metrics](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/dashboard_routes.py): `backend/app/api/dashboard_routes.py`
- [Commercial metrics](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/gestao_comercial_routes.py): `backend/app/api/gestao_comercial_routes.py`
- [KPI service](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/kpis_routes.py): `backend/app/api/kpis_routes.py`
- [Finance services](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/financeiro_routes.py): `backend/app/api/financeiro_routes.py`
- [Emissions](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/emissao_routes.py): `backend/app/api/emissao_routes.py`

### Backend platform

- [API application](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/api/auth_routes.py): `backend/app/api/auth_routes.py`
- [Access policy](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/security.py): `backend/app/security.py`
- [Lead rules](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/lead_utils.py): `backend/app/lead_utils.py`
- **PostgreSQL**

### External integrations

- [Followize sync](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/sync_followize.py): `backend/app/sync_followize.py`
- [Revenue sheets](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/sheets_receita.py): `backend/app/sheets_receita.py`
- [Attachment storage](https://github.com/kainonsolucoes1-beep/o2-solution/blob/main/backend/app/storage_r2.py): `backend/app/storage_r2.py`

### Other components

- **Business users**
- **Followize**
- **Cloud object storage**

## Connections

- Business users → Application routes: use (evidence: `frontend/src/App.tsx`)
- Application routes → Lead workspace: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Pipeline view: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Campaign tools: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Commercial analytics: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → KPI reporting: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Finance workspace: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Theme state: provides theme (evidence: `frontend/src/App.tsx`)
- Lead workspace → API client: requests data (evidence: `frontend/src/api/index.ts`)
- Pipeline view → API client: requests data (evidence: `frontend/src/api/index.ts`)
- Campaign tools → API client: requests data
- Dashboard → API client: requests data
- Commercial analytics → API client: requests data (evidence: `frontend/src/pages/GestaoComercial.tsx`)
- KPI reporting → API client: requests data (evidence: `frontend/src/pages/KPIs.tsx`)
- Finance workspace → API client: requests data
- API client → API application: calls API
- API application → Authentication: registers routes (evidence: `backend/app/main.py`)
- API application → Lead operations: registers routes (evidence: `backend/app/main.py`)
- API application → Pipeline service: registers routes (evidence: `backend/app/main.py`)
- API application → Campaign service: registers routes (evidence: `backend/app/main.py`)
- API application → Dashboard metrics: registers routes (evidence: `backend/app/main.py`)
- API application → Commercial metrics: registers routes (evidence: `backend/app/main.py`)
- API application → KPI service: registers routes (evidence: `backend/app/main.py`)
- Authentication → Access policy: checks access (evidence: `backend/app/api/auth_routes.py`)
- Authentication → PostgreSQL: reads users (evidence: `backend/app/api/auth_routes.py`)
- Lead operations → PostgreSQL: reads and writes (evidence: `backend/app/api/leads_routes.py`)
- Lead operations → Lead rules: uses rules (evidence: `backend/app/api/leads_routes.py`)
- Pipeline service → PostgreSQL: queries leads (evidence: `backend/app/api/pipeline_routes.py`)
- Campaign service → PostgreSQL: queries leads (evidence: `backend/app/api/campanhas_routes.py`)
- Dashboard metrics → PostgreSQL: queries metrics (evidence: `backend/app/api/dashboard_routes.py`)
- Commercial metrics → PostgreSQL: queries metrics (evidence: `backend/app/api/gestao_comercial_routes.py`)
- Commercial metrics → Lead rules: uses rules (evidence: `backend/app/api/gestao_comercial_routes.py`)
- KPI service → PostgreSQL: queries metrics (evidence: `backend/app/api/kpis_routes.py`)
- Finance services → PostgreSQL: reads and writes
- Emissions → PostgreSQL: reads and writes
- Followize sync → Followize: syncs leads
- Followize sync → PostgreSQL: updates leads (evidence: `backend/app/sync_followize.py`)
- Revenue sheets → PostgreSQL: syncs revenue (evidence: `backend/app/sheets_receita.py`)
- Lead operations → Attachment storage: handles attachments (evidence: `backend/app/api/leads_routes.py`)
- Attachment storage → Cloud object storage: stores files
