# simonequeiroz/cti_nexus architecture

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

- Interactive diagram: https://gitdiagram.com/simonequeiroz/cti_nexus
- Repository: https://github.com/simonequeiroz/cti_nexus

## Overview

CTI Nexus turns manually maintained commercial spreadsheets into validated, standardized client data, then exposes quality reports and analysis dashboards. The principal workflow is browser-side spreadsheet reading and correction, backend revalidation and approval, Python ETL persistence, and dashboard queries and insights. Separate branches support JWT authentication and administrator-managed access. The README documents the end-to-end flow; sampled source confirms selected validation, upload, authentication, and user-management responsibilities, but not every unsampled subsystem implementation.

Main entry points: [`frontend-vue/src/services/api.js`](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/api.js) (HTTP client), [`analytics-python/api.py`](https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/api.py) (ETL endpoint), [`frontend-vue/src/stores/uploadStore.js`](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/stores/uploadStore.js) (Upload workflow state), [`frontend-vue/src/views/PaginaUpload.vue`](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaUpload.vue) (Upload and validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Vue application"]
  node_upload_ui["Upload and validation<br/>[PaginaUpload.vue]"]
  node_spreadsheet["Spreadsheet reader<br/>[leituraPlanilha.js]"]
  node_browser_validation["Browser validation<br/>[validacao.js]"]
  node_upload_store["Upload workflow state<br/>[uploadStore.js]"]
  node_upload_service["Upload API client<br/>[uploadService.js]"]
  node_report["Quality report"]
  node_dashboard["Dashboard and insights"]
  node_dashboard_service["Dashboard API client"]
  node_api_client["HTTP client<br/>[api.js]"]
  node_login_ui["Login and access<br/>[PaginaLogin.vue]"]
  node_auth_store["Authentication state"]
  node_auth_service["Authentication client"]
  node_users_ui["User administration<br/>[PaginaUsuarios.vue]"]
  node_users_service["User API client<br/>[usuariosService.js]"]
end

subgraph group_java["Java API"]
  node_upload_controller["Upload endpoints"]
  node_upload_service_java["Upload orchestration<br/>[UploadService.java]"]
  node_java_validation["Server validation"]
  node_python_client["Python ETL client"]
  node_customer_queries["Customer and load queries"]
end

subgraph group_python["Python ETL"]
  node_etl_api["ETL endpoint<br/>[api.py]"]
  node_cleanup["Data cleaning<br/>[limpeza.py]"]
  node_analysis["Client statistics<br/>[analise.py]"]
  node_persistence["Batch persistence<br/>[banco.py]"]
  node_charts["Revenue boxplot<br/>[graficos.py]"]
end

subgraph group_identity["Identity and access"]
  node_auth_controller["Authentication endpoints"]
  node_auth_logic["Authentication rules"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_admin_controller["Admin user endpoints"]
  node_user_logic["User management rules"]
  node_user_repository["User repository"]
end

node_analyst(("Operations analyst"))
node_manager(("Manager"))
node_admin(("Administrator"))
node_database[("PostgreSQL Neon")]

node_analyst -->|"submits and corrects"| node_upload_ui
node_upload_ui -->|"reads spreadsheet"| node_spreadsheet
node_upload_ui -->|"validates in browser"| node_browser_validation
node_upload_ui -->|"updates workflow"| node_upload_store
node_upload_store -->|"sends approved rows"| node_upload_service
node_upload_service -->|"issues API request"| node_api_client
node_api_client -->|"calls upload API"| node_upload_controller
node_upload_controller -->|"delegates upload"| node_upload_service_java
node_upload_service_java -->|"revalidates rows"| node_java_validation
node_upload_service_java -->|"sends valid batch"| node_python_client
node_python_client -->|"posts ETL request"| node_etl_api
node_etl_api -->|"cleans data"| node_cleanup
node_etl_api -->|"computes statistics"| node_analysis
node_etl_api -->|"stores batch"| node_persistence
node_etl_api -->|"generates plot"| node_charts
node_persistence -->|"writes client data"| node_database
node_report -->|"shows quality results"| node_upload_store
node_manager -->|"views analysis"| node_dashboard
node_dashboard -->|"requests dashboard data"| node_upload_store
node_upload_store -->|"fetches panel data"| node_dashboard_service
node_dashboard_service -->|"issues API request"| node_api_client
node_api_client -->|"requests clients and loads"| node_customer_queries
node_customer_queries -->|"reads panel data"| node_database
node_admin -->|"authenticates"| node_login_ui
node_login_ui -->|"submits credentials"| node_auth_store
node_auth_store -->|"calls authentication"| node_auth_service
node_auth_service -->|"issues API request"| node_api_client
node_api_client -->|"calls auth endpoints"| node_auth_controller
node_auth_controller -->|"delegates authentication"| node_auth_logic
node_auth_logic -->|"generates login token"| node_jwt
node_auth_logic -->|"reads and writes users"| node_user_repository
node_user_repository -->|"persists user records"| node_database
node_admin -->|"manages accounts"| node_users_ui
node_users_ui -->|"requests user actions"| node_users_service
node_users_service -->|"issues API request"| node_api_client
node_api_client -->|"calls admin endpoints"| node_admin_controller
node_admin_controller -->|"delegates user management"| node_user_logic
node_user_logic -->|"manages user records"| node_user_repository

click node_upload_ui "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaUpload.vue"
click node_spreadsheet "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/utils/leituraPlanilha.js"
click node_browser_validation "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/utils/validacao.js"
click node_upload_store "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/stores/uploadStore.js"
click node_upload_service "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/uploadService.js"
click node_report "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaRelatorio.vue"
click node_dashboard "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaDashboard.vue"
click node_dashboard_service "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/dashboardService.js"
click node_api_client "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/api.js"
click node_login_ui "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaLogin.vue"
click node_auth_store "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/stores/autenticacaoStore.js"
click node_auth_service "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/autenticacaoService.js"
click node_users_ui "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaUsuarios.vue"
click node_users_service "https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/usuariosService.js"
click node_upload_controller "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/controller/UploadController.java"
click node_upload_service_java "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/UploadService.java"
click node_java_validation "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/ClienteValidacaoService.java"
click node_python_client "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/PythonEtlService.java"
click node_customer_queries "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/ConsultaCargaService.java"
click node_auth_controller "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/controller/AutenticacaoController.java"
click node_auth_logic "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/AutenticacaoService.java"
click node_jwt "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/security/JwtService.java"
click node_admin_controller "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/controller/AdminUsuarioController.java"
click node_user_logic "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/UsuarioService.java"
click node_user_repository "https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/repository/UsuarioRepository.java"
click node_etl_api "https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/api.py"
click node_cleanup "https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/limpeza.py"
click node_analysis "https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/analise.py"
click node_persistence "https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/banco.py"
click node_charts "https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/graficos.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_spreadsheet,node_browser_validation,node_upload_store,node_upload_service,node_report,node_dashboard,node_dashboard_service,node_api_client,node_login_ui,node_auth_store,node_auth_service,node_users_ui,node_users_service toneBlue
class node_upload_controller,node_upload_service_java,node_java_validation,node_python_client,node_customer_queries,node_database toneAmber
class node_etl_api,node_cleanup,node_analysis,node_persistence,node_charts toneMint
class node_auth_controller,node_auth_logic,node_jwt,node_admin_controller,node_user_logic,node_user_repository toneRose
class node_analyst,node_manager,node_admin toneIndigo
```

## Components

### Vue application

- [Upload and validation](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaUpload.vue): `frontend-vue/src/views/PaginaUpload.vue`
- [Spreadsheet reader](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/utils/leituraPlanilha.js): `frontend-vue/src/utils/leituraPlanilha.js`
- [Browser validation](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/utils/validacao.js): `frontend-vue/src/utils/validacao.js`
- [Upload workflow state](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/stores/uploadStore.js): `frontend-vue/src/stores/uploadStore.js`
- [Upload API client](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/uploadService.js): `frontend-vue/src/services/uploadService.js`
- [Quality report](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaRelatorio.vue): `frontend-vue/src/views/PaginaRelatorio.vue`
- [Dashboard and insights](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaDashboard.vue): `frontend-vue/src/views/PaginaDashboard.vue`
- [Dashboard API client](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/dashboardService.js): `frontend-vue/src/services/dashboardService.js`
- [HTTP client](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/api.js): `frontend-vue/src/services/api.js`
- [Login and access](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaLogin.vue): `frontend-vue/src/views/PaginaLogin.vue`
- [Authentication state](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/stores/autenticacaoStore.js): `frontend-vue/src/stores/autenticacaoStore.js`
- [Authentication client](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/autenticacaoService.js): `frontend-vue/src/services/autenticacaoService.js`
- [User administration](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/views/PaginaUsuarios.vue): `frontend-vue/src/views/PaginaUsuarios.vue`
- [User API client](https://github.com/simonequeiroz/cti_nexus/blob/main/frontend-vue/src/services/usuariosService.js): `frontend-vue/src/services/usuariosService.js`

### Java API

- [Upload endpoints](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/controller/UploadController.java): `backend-java/src/main/java/br/com/ctinexus/controller/UploadController.java`
- [Upload orchestration](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/UploadService.java): `backend-java/src/main/java/br/com/ctinexus/service/UploadService.java`
- [Server validation](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/ClienteValidacaoService.java): `backend-java/src/main/java/br/com/ctinexus/service/ClienteValidacaoService.java`
- [Python ETL client](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/PythonEtlService.java): `backend-java/src/main/java/br/com/ctinexus/service/PythonEtlService.java`
- [Customer and load queries](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/ConsultaCargaService.java): `backend-java/src/main/java/br/com/ctinexus/service/ConsultaCargaService.java`

### Python ETL

- [ETL endpoint](https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/api.py): `analytics-python/api.py`
- [Data cleaning](https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/limpeza.py): `analytics-python/limpeza.py`
- [Client statistics](https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/analise.py): `analytics-python/analise.py`
- [Batch persistence](https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/banco.py): `analytics-python/banco.py`
- [Revenue boxplot](https://github.com/simonequeiroz/cti_nexus/blob/main/analytics-python/graficos.py): `analytics-python/graficos.py`

### Identity and access

- [Authentication endpoints](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/controller/AutenticacaoController.java): `backend-java/src/main/java/br/com/ctinexus/controller/AutenticacaoController.java`
- [Authentication rules](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/AutenticacaoService.java): `backend-java/src/main/java/br/com/ctinexus/service/AutenticacaoService.java`
- [JWT service](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/security/JwtService.java): `backend-java/src/main/java/br/com/ctinexus/security/JwtService.java`
- [Admin user endpoints](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/controller/AdminUsuarioController.java): `backend-java/src/main/java/br/com/ctinexus/controller/AdminUsuarioController.java`
- [User management rules](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/service/UsuarioService.java): `backend-java/src/main/java/br/com/ctinexus/service/UsuarioService.java`
- [User repository](https://github.com/simonequeiroz/cti_nexus/blob/main/backend-java/src/main/java/br/com/ctinexus/repository/UsuarioRepository.java): `backend-java/src/main/java/br/com/ctinexus/repository/UsuarioRepository.java`

### Other components

- **Operations analyst**
- **Manager**
- **Administrator**
- **PostgreSQL Neon**

## Connections

- Operations analyst → Upload and validation: submits and corrects
- Upload and validation → Spreadsheet reader: reads spreadsheet
- Upload and validation → Browser validation: validates in browser
- Upload and validation → Upload workflow state: updates workflow
- Upload workflow state → Upload API client: sends approved rows (evidence: `frontend-vue/src/stores/uploadStore.js`)
- Upload API client → HTTP client: issues API request (evidence: `frontend-vue/src/services/uploadService.js`)
- HTTP client → Upload endpoints: calls upload API
- Upload endpoints → Upload orchestration: delegates upload
- Upload orchestration → Server validation: revalidates rows (evidence: `backend-java/src/main/java/br/com/ctinexus/service/UploadService.java`)
- Upload orchestration → Python ETL client: sends valid batch (evidence: `backend-java/src/main/java/br/com/ctinexus/service/UploadService.java`)
- Python ETL client → ETL endpoint: posts ETL request
- ETL endpoint → Data cleaning: cleans data (evidence: `analytics-python/api.py`)
- ETL endpoint → Client statistics: computes statistics (evidence: `analytics-python/api.py`)
- ETL endpoint → Batch persistence: stores batch (evidence: `analytics-python/api.py`)
- ETL endpoint → Revenue boxplot: generates plot (evidence: `analytics-python/api.py`)
- Batch persistence → PostgreSQL Neon: writes client data
- Quality report → Upload workflow state: shows quality results
- Manager → Dashboard and insights: views analysis
- Dashboard and insights → Upload workflow state: requests dashboard data
- Upload workflow state → Dashboard API client: fetches panel data (evidence: `frontend-vue/src/stores/uploadStore.js`)
- Dashboard API client → HTTP client: issues API request (evidence: `frontend-vue/src/services/dashboardService.js`)
- HTTP client → Customer and load queries: requests clients and loads
- Customer and load queries → PostgreSQL Neon: reads panel data
- Administrator → Login and access: authenticates
- Login and access → Authentication state: submits credentials
- Authentication state → Authentication client: calls authentication
- Authentication client → HTTP client: issues API request (evidence: `frontend-vue/src/services/autenticacaoService.js`)
- HTTP client → Authentication endpoints: calls auth endpoints
- Authentication endpoints → Authentication rules: delegates authentication (evidence: `backend-java/src/main/java/br/com/ctinexus/controller/AutenticacaoController.java`)
- Authentication rules → JWT service: generates login token (evidence: `backend-java/src/main/java/br/com/ctinexus/service/AutenticacaoService.java`)
- Authentication rules → User repository: reads and writes users (evidence: `backend-java/src/main/java/br/com/ctinexus/service/AutenticacaoService.java`)
- User repository → PostgreSQL Neon: persists user records
- Administrator → User administration: manages accounts
- User administration → User API client: requests user actions
- User API client → HTTP client: issues API request (evidence: `frontend-vue/src/services/usuariosService.js`)
- HTTP client → Admin user endpoints: calls admin endpoints
- Admin user endpoints → User management rules: delegates user management (evidence: `backend-java/src/main/java/br/com/ctinexus/controller/AdminUsuarioController.java`)
- User management rules → User repository: manages user records (evidence: `backend-java/src/main/java/br/com/ctinexus/service/UsuarioService.java`)
