# sqlalan/cti architecture

> Architecture diagram of the GitHub repository sqlalan/cti, 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/sqlalan/cti
- Repository: https://github.com/sqlalan/cti

## Overview

CTI Insights turns manually maintained client spreadsheets into validated, standardized client data, persisted records, statistical summaries and dashboard insights. The main workflow runs from browser-side spreadsheet checks through Spring validation and a Python ETL to PostgreSQL; Spring then serves dashboard data back to the Vue interface. Separate capabilities include account access and administration, manual client and contract management, processing history, and a file-based statistical report. Some backend routes and frontend components are unsampled, so links for those branches rely on README documentation.

Main entry points: [`frontend/src/services/api.js`](https://github.com/sqlalan/cti/blob/main/frontend/src/services/api.js) (API client), [`analytics-python/main.py`](https://github.com/sqlalan/cti/blob/main/analytics-python/main.py) (ETL orchestration), [`frontend/src/pages/Upload.vue`](https://github.com/sqlalan/cti/blob/main/frontend/src/pages/Upload.vue) (Spreadsheet upload), [`backend/src/main/java/br/com/cti/insights/service/UploadService.java`](https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/UploadService.java) (Upload validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Vue frontend"]
  node_upload_ui["Spreadsheet upload<br/>[Upload.vue]"]
  node_sheet_schema["Sheet validation<br/>[esquemaPlanilha.js]"]
  node_upload_state["Upload state<br/>[uploadStore.js]"]
  node_frontend_api["API client<br/>[api.js]"]
  node_dashboard_ui["Dashboard<br/>[DashboardView.vue]"]
  node_history_ui["Processing history"]
  node_auth_ui["Login and accounts<br/>[Login.vue]"]
end

subgraph group_backend["Spring backend"]
  node_upload_service["Upload validation<br/>[UploadService.java]"]
  node_client_dto["Validated row DTO<br/>[ClienteDTO.java]"]
  node_etl_client["Python ETL client"]
  node_dashboard_service["Dashboard reader"]
  node_client_service["Client management"]
  node_account_service["Account management"]
end

subgraph group_etl["Python ETL"]
  node_python_api["ETL API<br/>[api.py]"]
  node_etl_orchestrator["ETL orchestration<br/>[main.py]"]
  node_cleaning["Data cleaning<br/>[limpeza.py]"]
  node_statistics["Statistical analysis<br/>[analise.py]"]
  node_persistence["ETL persistence<br/>[banco.py]"]
  node_insights["Insight generation<br/>[insights.py]"]
end

subgraph group_analytics["Analytics"]
  node_report["Offline report<br/>[relatorio.py]"]
end

node_consultor(("Consultor"))
node_postgres[("PostgreSQL")]

node_consultor -->|"uploads sheet"| node_upload_ui
node_upload_ui -->|"validates rows"| node_sheet_schema
node_upload_ui -->|"submits batch"| node_upload_state
node_upload_state -.->|"sends upload"| node_frontend_api
node_frontend_api -->|"posts batch"| node_upload_service
node_upload_service -->|"validates rows"| node_client_dto
node_upload_service -->|"forwards valid rows"| node_etl_client
node_etl_client -->|"posts ETL request"| node_python_api
node_python_api -->|"dispatches ETL"| node_etl_orchestrator
node_etl_orchestrator -->|"cleans data"| node_cleaning
node_etl_orchestrator -->|"calculates statistics"| node_statistics
node_etl_orchestrator -->|"persists results"| node_persistence
node_statistics -->|"uses analysis"| node_insights
node_persistence -->|"writes ETL data"| node_postgres
node_dashboard_ui -->|"requests dashboard"| node_frontend_api
node_frontend_api -->|"requests dashboard"| node_dashboard_service
node_dashboard_service -->|"reads dashboard data"| node_postgres
node_history_ui -->|"loads batches"| node_frontend_api
node_auth_ui -->|"submits credentials"| node_frontend_api
node_account_service -.->|"stores accounts"| node_postgres
node_client_service -.->|"manages client records"| node_postgres
node_report -.->|"produces report"| node_statistics

click node_upload_ui "https://github.com/sqlalan/cti/blob/main/frontend/src/pages/Upload.vue"
click node_sheet_schema "https://github.com/sqlalan/cti/blob/main/frontend/src/dados/esquemaPlanilha.js"
click node_upload_state "https://github.com/sqlalan/cti/blob/main/frontend/src/stores/uploadStore.js"
click node_frontend_api "https://github.com/sqlalan/cti/blob/main/frontend/src/services/api.js"
click node_dashboard_ui "https://github.com/sqlalan/cti/blob/main/frontend/src/views/DashboardView.vue"
click node_history_ui "https://github.com/sqlalan/cti/blob/main/frontend/src/components/HistoricoProcessamentos.vue"
click node_auth_ui "https://github.com/sqlalan/cti/blob/main/frontend/src/pages/Login.vue"
click node_upload_service "https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/UploadService.java"
click node_client_dto "https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/dto/ClienteDTO.java"
click node_etl_client "https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/PythonEtlService.java"
click node_dashboard_service "https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/DashboardService.java"
click node_client_service "https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/ClienteService.java"
click node_account_service "https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/UsuarioService.java"
click node_python_api "https://github.com/sqlalan/cti/blob/main/analytics-python/api.py"
click node_etl_orchestrator "https://github.com/sqlalan/cti/blob/main/analytics-python/main.py"
click node_cleaning "https://github.com/sqlalan/cti/blob/main/analytics-python/limpeza.py"
click node_statistics "https://github.com/sqlalan/cti/blob/main/analytics-python/analise.py"
click node_persistence "https://github.com/sqlalan/cti/blob/main/analytics-python/banco.py"
click node_insights "https://github.com/sqlalan/cti/blob/main/analytics-python/insights.py"
click node_report "https://github.com/sqlalan/cti/blob/main/analytics-python/relatorio.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_upload_ui,node_sheet_schema,node_upload_state,node_frontend_api,node_dashboard_ui,node_history_ui,node_auth_ui toneBlue
class node_upload_service,node_client_dto,node_etl_client,node_dashboard_service,node_client_service,node_account_service,node_postgres toneAmber
class node_python_api,node_etl_orchestrator,node_cleaning,node_statistics,node_persistence,node_insights toneMint
class node_report toneRose
class node_consultor toneIndigo
```

## Components

### Vue frontend

- [Spreadsheet upload](https://github.com/sqlalan/cti/blob/main/frontend/src/pages/Upload.vue): `frontend/src/pages/Upload.vue`
- [Sheet validation](https://github.com/sqlalan/cti/blob/main/frontend/src/dados/esquemaPlanilha.js): `frontend/src/dados/esquemaPlanilha.js`
- [Upload state](https://github.com/sqlalan/cti/blob/main/frontend/src/stores/uploadStore.js): `frontend/src/stores/uploadStore.js`
- [API client](https://github.com/sqlalan/cti/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Dashboard](https://github.com/sqlalan/cti/blob/main/frontend/src/views/DashboardView.vue): `frontend/src/views/DashboardView.vue`
- [Processing history](https://github.com/sqlalan/cti/blob/main/frontend/src/components/HistoricoProcessamentos.vue): `frontend/src/components/HistoricoProcessamentos.vue`
- [Login and accounts](https://github.com/sqlalan/cti/blob/main/frontend/src/pages/Login.vue): `frontend/src/pages/Login.vue`

### Spring backend

- [Upload validation](https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/UploadService.java): `backend/src/main/java/br/com/cti/insights/service/UploadService.java`
- [Validated row DTO](https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/dto/ClienteDTO.java): `backend/src/main/java/br/com/cti/insights/dto/ClienteDTO.java`
- [Python ETL client](https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/PythonEtlService.java): `backend/src/main/java/br/com/cti/insights/service/PythonEtlService.java`
- [Dashboard reader](https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/DashboardService.java): `backend/src/main/java/br/com/cti/insights/service/DashboardService.java`
- [Client management](https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/ClienteService.java): `backend/src/main/java/br/com/cti/insights/service/ClienteService.java`
- [Account management](https://github.com/sqlalan/cti/blob/main/backend/src/main/java/br/com/cti/insights/service/UsuarioService.java): `backend/src/main/java/br/com/cti/insights/service/UsuarioService.java`

### Python ETL

- [ETL API](https://github.com/sqlalan/cti/blob/main/analytics-python/api.py): `analytics-python/api.py`
- [ETL orchestration](https://github.com/sqlalan/cti/blob/main/analytics-python/main.py): `analytics-python/main.py`
- [Data cleaning](https://github.com/sqlalan/cti/blob/main/analytics-python/limpeza.py): `analytics-python/limpeza.py`
- [Statistical analysis](https://github.com/sqlalan/cti/blob/main/analytics-python/analise.py): `analytics-python/analise.py`
- [ETL persistence](https://github.com/sqlalan/cti/blob/main/analytics-python/banco.py): `analytics-python/banco.py`
- [Insight generation](https://github.com/sqlalan/cti/blob/main/analytics-python/insights.py): `analytics-python/insights.py`

### Analytics

- [Offline report](https://github.com/sqlalan/cti/blob/main/analytics-python/relatorio.py): `analytics-python/relatorio.py`

### Other components

- **Consultor**
- **PostgreSQL**

## Connections

- Consultor → Spreadsheet upload: uploads sheet (evidence: `README.md`)
- Spreadsheet upload → Sheet validation: validates rows (evidence: `frontend/src/pages/Upload.vue`)
- Spreadsheet upload → Upload state: submits batch (evidence: `frontend/src/pages/Upload.vue`)
- Upload state → API client: sends upload (evidence: `frontend/src/stores/uploadStore.js`)
- API client → Upload validation: posts batch (evidence: `README.md`)
- Upload validation → Validated row DTO: validates rows (evidence: `backend/src/main/java/br/com/cti/insights/service/UploadService.java`)
- Upload validation → Python ETL client: forwards valid rows (evidence: `backend/src/main/java/br/com/cti/insights/service/UploadService.java`)
- Python ETL client → ETL API: posts ETL request (evidence: `README.md`)
- ETL API → ETL orchestration: dispatches ETL (evidence: `README.md`)
- ETL orchestration → Data cleaning: cleans data (evidence: `analytics-python/main.py`)
- ETL orchestration → Statistical analysis: calculates statistics (evidence: `analytics-python/main.py`)
- ETL orchestration → ETL persistence: persists results (evidence: `analytics-python/main.py`)
- Statistical analysis → Insight generation: uses analysis (evidence: `analytics-python/analise.py`)
- ETL persistence → PostgreSQL: writes ETL data (evidence: `README.md`)
- Dashboard → API client: requests dashboard (evidence: `README.md`)
- API client → Dashboard reader: requests dashboard (evidence: `README.md`)
- Dashboard reader → PostgreSQL: reads dashboard data (evidence: `README.md`)
- Processing history → API client: loads batches (evidence: `frontend/src/components/HistoricoProcessamentos.vue`)
- Login and accounts → API client: submits credentials
- Account management → PostgreSQL: stores accounts
- Client management → PostgreSQL: manages client records
- Offline report → Statistical analysis: produces report
