# maikezzk7-spec/cti architecture

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

## Overview

This is a CTI customer-insights portal: users upload customer spreadsheets, the backend validates and forwards accepted rows to Python ETL/analytics, and the frontend presents customer, dashboard, chart, and report views. Account registration, login, session checks, and administrator user management support access to the portal. The source index and excerpts establish the upload and analytics handoffs; several view implementations and runtime integrations were not sampled, so those links are omitted or marked unverified.

Main entry points: [`frontend/src/router/index.js`](https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/router/index.js) (Route guard), [`analytics-python/main.py`](https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/main.py) (ETL entry point), [`backend/src/main/java/com/cti/provedor/controller/AuthController.java`](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/controller/AuthController.java) (Auth endpoints), [`backend/src/main/java/com/cti/provedor/service/AuthService.java`](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/AuthService.java) (Auth service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Portal UI"]
  node_routes["Route guard<br/>[index.js]"]
  node_customer_ui["Customer browser<br/>[ClientesView.vue]"]
  node_portal_views["Insights views"]
  node_upload_view["Upload screen<br/>[UploadView.vue]"]
  node_upload_state["Upload state<br/>[uploadStore.js]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_access["Accounts &amp; Access"]
  node_auth_ui["Auth state<br/>[auth.js]"]
  node_auth_api["Auth endpoints"]
  node_auth_service["Auth service<br/>[AuthService.java]"]
  node_user_admin["User administration"]
  node_user_store[("User repository")]
  node_user_model["User account<br/>[Usuario.java]"]
  node_jwt["JWT service<br/>[JwtService.java]"]
end

subgraph group_upload["Customer Upload"]
  node_upload_api["Upload endpoint"]
  node_upload_service["Upload coordinator<br/>[UploadService.java]"]
  node_row_validator["Row validation"]
  node_python_etl["Python ETL bridge"]
end

subgraph group_analytics["ETL &amp; Analytics"]
  node_etl_entry["ETL entry point<br/>[main.py]"]
  node_cleanup["Spreadsheet cleanup<br/>[limpeza.py]"]
  node_analysis["Customer analysis<br/>[analise.py]"]
  node_insights["Insight generation<br/>[insights.py]"]
  node_analytics_db["Analytics database access<br/>[banco.py]"]
  node_customer_data[("Customer data store")]
end

node_user(("Portal user"))
node_backend_api["Portal backend"]

node_user -->|"opens portal"| node_routes
node_routes -->|"routes to"| node_portal_views
node_routes -->|"routes to"| node_upload_view
node_routes -->|"routes to"| node_customer_ui
node_routes -->|"checks session"| node_auth_ui
node_customer_ui -->|"reads customer data"| node_upload_state
node_auth_ui -->|"uses API"| node_api_client
node_upload_view -.->|"uses upload state"| node_upload_state
node_upload_state -.->|"submits upload"| node_api_client
node_api_client -.->|"HTTP requests"| node_backend_api
node_backend_api -.->|"dispatches auth"| node_auth_api
node_backend_api -.->|"dispatches upload"| node_upload_api
node_auth_api -->|"calls"| node_auth_service
node_auth_api -->|"calls"| node_user_admin
node_auth_service -->|"issues token"| node_jwt
node_auth_service -->|"reads and saves"| node_user_store
node_user_admin -->|"manages accounts"| node_user_store
node_user_store -->|"persists"| node_user_model
node_upload_api -->|"calls"| node_upload_service
node_upload_service -->|"validates rows"| node_row_validator
node_upload_service -->|"forwards accepted rows"| node_python_etl
node_python_etl -.->|"invokes ETL"| node_etl_entry
node_etl_entry -->|"calls cleanup"| node_cleanup
node_etl_entry -->|"calls analysis"| node_analysis
node_etl_entry -->|"uses database access"| node_analytics_db
node_analysis -->|"uses cleaned data"| node_cleanup
node_analysis -->|"uses insights"| node_insights
node_analytics_db -.->|"reads and writes"| node_customer_data

click node_routes "https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/router/index.js"
click node_customer_ui "https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/views/ClientesView.vue"
click node_portal_views "https://github.com/maikezzk7-spec/cti/tree/master/frontend/src/views"
click node_upload_view "https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/views/UploadView.vue"
click node_upload_state "https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/stores/uploadStore.js"
click node_api_client "https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/services/api.js"
click node_auth_ui "https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/stores/auth.js"
click node_auth_api "https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/controller/AuthController.java"
click node_auth_service "https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/AuthService.java"
click node_user_admin "https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/UsuarioService.java"
click node_user_store "https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/repository/UsuarioRepository.java"
click node_user_model "https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/model/Usuario.java"
click node_jwt "https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/config/JwtService.java"
click node_upload_api "https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/controller/UploadController.java"
click node_upload_service "https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/UploadService.java"
click node_row_validator "https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/ClienteValidacaoService.java"
click node_python_etl "https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/PythonEtlService.java"
click node_etl_entry "https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/main.py"
click node_cleanup "https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/limpeza.py"
click node_analysis "https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/analise.py"
click node_insights "https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/insights.py"
click node_analytics_db "https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/banco.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_routes,node_customer_ui,node_portal_views,node_upload_view,node_upload_state,node_api_client,node_user toneBlue
class node_auth_ui,node_auth_api,node_auth_service,node_user_admin,node_user_store,node_user_model,node_jwt toneAmber
class node_upload_api,node_upload_service,node_row_validator,node_python_etl toneMint
class node_etl_entry,node_cleanup,node_analysis,node_insights,node_analytics_db,node_customer_data toneRose
class node_backend_api toneIndigo
```

## Components

### Portal UI

- [Route guard](https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/router/index.js): `frontend/src/router/index.js`
- [Customer browser](https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/views/ClientesView.vue): `frontend/src/views/ClientesView.vue`
- [Insights views](https://github.com/maikezzk7-spec/cti/tree/master/frontend/src/views): `frontend/src/views`
- [Upload screen](https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/views/UploadView.vue): `frontend/src/views/UploadView.vue`
- [Upload state](https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/stores/uploadStore.js): `frontend/src/stores/uploadStore.js`
- [API client](https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/services/api.js): `frontend/src/services/api.js`

### Accounts & Access

- [Auth state](https://github.com/maikezzk7-spec/cti/blob/master/frontend/src/stores/auth.js): `frontend/src/stores/auth.js`
- [Auth endpoints](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/controller/AuthController.java): `backend/src/main/java/com/cti/provedor/controller/AuthController.java`
- [Auth service](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/AuthService.java): `backend/src/main/java/com/cti/provedor/service/AuthService.java`
- [User administration](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/UsuarioService.java): `backend/src/main/java/com/cti/provedor/service/UsuarioService.java`
- [User repository](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/repository/UsuarioRepository.java): `backend/src/main/java/com/cti/provedor/repository/UsuarioRepository.java`
- [User account](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/model/Usuario.java): `backend/src/main/java/com/cti/provedor/model/Usuario.java`
- [JWT service](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/config/JwtService.java): `backend/src/main/java/com/cti/provedor/config/JwtService.java`

### Customer Upload

- [Upload endpoint](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/controller/UploadController.java): `backend/src/main/java/com/cti/provedor/controller/UploadController.java`
- [Upload coordinator](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/UploadService.java): `backend/src/main/java/com/cti/provedor/service/UploadService.java`
- [Row validation](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/ClienteValidacaoService.java): `backend/src/main/java/com/cti/provedor/service/ClienteValidacaoService.java`
- [Python ETL bridge](https://github.com/maikezzk7-spec/cti/blob/master/backend/src/main/java/com/cti/provedor/service/PythonEtlService.java): `backend/src/main/java/com/cti/provedor/service/PythonEtlService.java`

### ETL & Analytics

- [ETL entry point](https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/main.py): `analytics-python/main.py`
- [Spreadsheet cleanup](https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/limpeza.py): `analytics-python/limpeza.py`
- [Customer analysis](https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/analise.py): `analytics-python/analise.py`
- [Insight generation](https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/insights.py): `analytics-python/insights.py`
- [Analytics database access](https://github.com/maikezzk7-spec/cti/blob/master/analytics-python/banco.py): `analytics-python/banco.py`
- **Customer data store**

### Other components

- **Portal user**
- **Portal backend**

## Connections

- Portal user → Route guard: opens portal (evidence: `frontend/src/router/index.js`)
- Route guard → Insights views: routes to (evidence: `frontend/src/router/index.js`)
- Route guard → Upload screen: routes to (evidence: `frontend/src/router/index.js`)
- Route guard → Customer browser: routes to (evidence: `frontend/src/router/index.js`)
- Route guard → Auth state: checks session (evidence: `frontend/src/router/index.js`)
- Customer browser → Upload state: reads customer data (evidence: `frontend/src/views/ClientesView.vue`)
- Auth state → API client: uses API (evidence: `frontend/src/stores/auth.js`)
- Upload screen → Upload state: uses upload state
- Upload state → API client: submits upload
- API client → Portal backend: HTTP requests
- Portal backend → Auth endpoints: dispatches auth
- Portal backend → Upload endpoint: dispatches upload
- Auth endpoints → Auth service: calls (evidence: `backend/src/main/java/com/cti/provedor/controller/AuthController.java`)
- Auth endpoints → User administration: calls (evidence: `backend/src/main/java/com/cti/provedor/controller/AuthController.java`)
- Auth service → JWT service: issues token (evidence: `backend/src/main/java/com/cti/provedor/service/AuthService.java`)
- Auth service → User repository: reads and saves (evidence: `backend/src/main/java/com/cti/provedor/service/AuthService.java`)
- User administration → User repository: manages accounts (evidence: `backend/src/main/java/com/cti/provedor/service/UsuarioService.java`)
- User repository → User account: persists (evidence: `backend/src/main/java/com/cti/provedor/repository/UsuarioRepository.java`)
- Upload endpoint → Upload coordinator: calls (evidence: `backend/src/main/java/com/cti/provedor/controller/UploadController.java`)
- Upload coordinator → Row validation: validates rows (evidence: `backend/src/main/java/com/cti/provedor/service/UploadService.java`)
- Upload coordinator → Python ETL bridge: forwards accepted rows (evidence: `backend/src/main/java/com/cti/provedor/service/UploadService.java`)
- Python ETL bridge → ETL entry point: invokes ETL
- ETL entry point → Spreadsheet cleanup: calls cleanup (evidence: `analytics-python/main.py`)
- ETL entry point → Customer analysis: calls analysis (evidence: `analytics-python/main.py`)
- ETL entry point → Analytics database access: uses database access (evidence: `analytics-python/main.py`)
- Customer analysis → Spreadsheet cleanup: uses cleaned data (evidence: `analytics-python/analise.py`)
- Customer analysis → Insight generation: uses insights (evidence: `analytics-python/analise.py`)
- Analytics database access → Customer data store: reads and writes
