# sqlalan/insightflow architecture

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

## Overview

InsightFlow CTI turns manually maintained Excel customer data into standardized records, persisted commercial data, and dashboard/report insights. The main workflow is spreadsheet upload, validation, Python processing, persistence, and presentation; the repository also includes customer administration and authentication. The README documents the overall architecture, while sampled source supports several internal calls. Some frontend/API wiring and unsampled subsystems are represented only where documented.

Main entry points: [`frontend-vue/src/services/api.js`](https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/services/api.js) (API client), [`frontend-vue/src/router/index.js`](https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/router/index.js) (Web shell and routing), [`backend-java/src/main/java/br/senai/ctiinsights/service/ImportacaoService.java`](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/ImportacaoService.java) (Import orchestration), [`analytics-python/analise.py`](https://github.com/sqlalan/insightflow/blob/main/analytics-python/analise.py) (Statistical analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Vue application"]
  node_web["Web shell and routing<br/>[index.js]"]
  node_upload_ui["Spreadsheet upload<br/>[UploadView.vue]"]
  node_dashboard_ui["Dashboard<br/>[DashboardView.vue]"]
  node_reports_ui["Reports and export<br/>[RelatoriosView.vue]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["Spring API"]
  node_upload_controller["Upload endpoint"]
  node_sheet_validation["Spreadsheet validation"]
  node_import["Import orchestration"]
  node_analysis_runner["Python process runner"]
  node_dashboard_api["Dashboard endpoints"]
  node_dashboard_service["Dashboard services"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_customer_api["Customer administration"]
  node_customer_service["Customer rules"]
end

subgraph group_analytics["Python analytics"]
  node_clean["Data cleaning<br/>[limpeza.py]"]
  node_analysis["Statistical analysis<br/>[analise.py]"]
  node_insights["Insight generation<br/>[insights.py]"]
  node_charts["Chart generation<br/>[graficos.py]"]
end

subgraph group_persistence["Commercial data"]
  node_customer_data[("Customer records<br/>[Cliente.java]")]
  node_customer_repository["Customer repository"]
end

node_user(("CTI user"))
node_cloud_db[("PostgreSQL database")]

node_user -->|"uses"| node_web
node_web -->|"routes to"| node_upload_ui
node_web -->|"routes to"| node_dashboard_ui
node_web -->|"routes to"| node_reports_ui
node_upload_ui -.->|"submits through"| node_api_client
node_dashboard_ui -.->|"loads data through"| node_api_client
node_reports_ui -->|"loads data through"| node_api_client
node_api_client -.->|"calls API"| node_upload_controller
node_api_client -.->|"calls API"| node_dashboard_api
node_upload_controller -.->|"delegates to"| node_import
node_import -->|"validates with"| node_sheet_validation
node_import -->|"runs analysis"| node_analysis_runner
node_analysis_runner -->|"executes script"| node_analysis
node_analysis -->|"imports and uses"| node_clean
node_analysis -->|"imports and uses"| node_insights
node_analysis -->|"imports and uses"| node_charts
node_import -->|"persists records"| node_customer_repository
node_customer_service -->|"reads and writes"| node_customer_repository
node_customer_api -->|"delegates to"| node_customer_service
node_dashboard_api -->|"delegates to"| node_dashboard_service
node_customer_repository -->|"stores entities"| node_customer_data
node_customer_data -.->|"persisted in"| node_cloud_db
node_user -.->|"authenticates with"| node_auth
node_analysis_runner -.->|"feeds persisted results"| node_cloud_db

click node_web "https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/router/index.js"
click node_upload_ui "https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/views/UploadView.vue"
click node_dashboard_ui "https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/views/DashboardView.vue"
click node_reports_ui "https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/views/RelatoriosView.vue"
click node_api_client "https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/services/api.js"
click node_upload_controller "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/controller/UploadController.java"
click node_sheet_validation "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/PlanilhaService.java"
click node_import "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/ImportacaoService.java"
click node_analysis_runner "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/AnaliseService.java"
click node_dashboard_api "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/controller/DashboardController.java"
click node_dashboard_service "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/DashboardService.java"
click node_auth "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/AuthService.java"
click node_customer_api "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/controller/ClienteController.java"
click node_customer_service "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/ClienteService.java"
click node_clean "https://github.com/sqlalan/insightflow/blob/main/analytics-python/limpeza.py"
click node_analysis "https://github.com/sqlalan/insightflow/blob/main/analytics-python/analise.py"
click node_insights "https://github.com/sqlalan/insightflow/blob/main/analytics-python/insights.py"
click node_charts "https://github.com/sqlalan/insightflow/blob/main/analytics-python/graficos.py"
click node_customer_data "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/domain/Cliente.java"
click node_customer_repository "https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/repository/ClienteRepository.java"

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_web,node_upload_ui,node_dashboard_ui,node_reports_ui,node_api_client,node_user toneBlue
class node_upload_controller,node_sheet_validation,node_import,node_analysis_runner,node_dashboard_api,node_dashboard_service,node_auth,node_customer_api,node_customer_service,node_cloud_db toneAmber
class node_clean,node_analysis,node_insights,node_charts toneMint
class node_customer_data,node_customer_repository toneRose
```

## Components

### Vue application

- [Web shell and routing](https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/router/index.js): `frontend-vue/src/router/index.js`
- [Spreadsheet upload](https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/views/UploadView.vue): `frontend-vue/src/views/UploadView.vue`
- [Dashboard](https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/views/DashboardView.vue): `frontend-vue/src/views/DashboardView.vue`
- [Reports and export](https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/views/RelatoriosView.vue): `frontend-vue/src/views/RelatoriosView.vue`
- [API client](https://github.com/sqlalan/insightflow/blob/main/frontend-vue/src/services/api.js): `frontend-vue/src/services/api.js`

### Spring API

- [Upload endpoint](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/controller/UploadController.java): `backend-java/src/main/java/br/senai/ctiinsights/controller/UploadController.java`
- [Spreadsheet validation](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/PlanilhaService.java): `backend-java/src/main/java/br/senai/ctiinsights/service/PlanilhaService.java`
- [Import orchestration](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/ImportacaoService.java): `backend-java/src/main/java/br/senai/ctiinsights/service/ImportacaoService.java`
- [Python process runner](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/AnaliseService.java): `backend-java/src/main/java/br/senai/ctiinsights/service/AnaliseService.java`
- [Dashboard endpoints](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/controller/DashboardController.java): `backend-java/src/main/java/br/senai/ctiinsights/controller/DashboardController.java`
- [Dashboard services](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/DashboardService.java): `backend-java/src/main/java/br/senai/ctiinsights/service/DashboardService.java`
- [Authentication](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/AuthService.java): `backend-java/src/main/java/br/senai/ctiinsights/service/AuthService.java`
- [Customer administration](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/controller/ClienteController.java): `backend-java/src/main/java/br/senai/ctiinsights/controller/ClienteController.java`
- [Customer rules](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/service/ClienteService.java): `backend-java/src/main/java/br/senai/ctiinsights/service/ClienteService.java`

### Python analytics

- [Data cleaning](https://github.com/sqlalan/insightflow/blob/main/analytics-python/limpeza.py): `analytics-python/limpeza.py`
- [Statistical analysis](https://github.com/sqlalan/insightflow/blob/main/analytics-python/analise.py): `analytics-python/analise.py`
- [Insight generation](https://github.com/sqlalan/insightflow/blob/main/analytics-python/insights.py): `analytics-python/insights.py`
- [Chart generation](https://github.com/sqlalan/insightflow/blob/main/analytics-python/graficos.py): `analytics-python/graficos.py`

### Commercial data

- [Customer records](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/domain/Cliente.java): `backend-java/src/main/java/br/senai/ctiinsights/domain/Cliente.java`
- [Customer repository](https://github.com/sqlalan/insightflow/blob/main/backend-java/src/main/java/br/senai/ctiinsights/repository/ClienteRepository.java): `backend-java/src/main/java/br/senai/ctiinsights/repository/ClienteRepository.java`

### Other components

- **CTI user**
- **PostgreSQL database**

## Connections

- CTI user → Web shell and routing: uses (evidence: `README.md`)
- Web shell and routing → Spreadsheet upload: routes to (evidence: `frontend-vue/src/router/index.js`)
- Web shell and routing → Dashboard: routes to (evidence: `frontend-vue/src/router/index.js`)
- Web shell and routing → Reports and export: routes to (evidence: `frontend-vue/src/router/index.js`)
- Spreadsheet upload → API client: submits through
- Dashboard → API client: loads data through
- Reports and export → API client: loads data through (evidence: `frontend-vue/src/views/RelatoriosView.vue`)
- API client → Upload endpoint: calls API
- API client → Dashboard endpoints: calls API
- Upload endpoint → Import orchestration: delegates to
- Import orchestration → Spreadsheet validation: validates with (evidence: `backend-java/src/main/java/br/senai/ctiinsights/service/ImportacaoService.java`)
- Import orchestration → Python process runner: runs analysis (evidence: `backend-java/src/main/java/br/senai/ctiinsights/service/ImportacaoService.java`)
- Python process runner → Statistical analysis: executes script (evidence: `backend-java/src/main/java/br/senai/ctiinsights/service/AnaliseService.java`)
- Statistical analysis → Data cleaning: imports and uses (evidence: `analytics-python/analise.py`)
- Statistical analysis → Insight generation: imports and uses (evidence: `analytics-python/analise.py`)
- Statistical analysis → Chart generation: imports and uses (evidence: `analytics-python/analise.py`)
- Import orchestration → Customer repository: persists records (evidence: `backend-java/src/main/java/br/senai/ctiinsights/service/ImportacaoService.java`)
- Customer rules → Customer repository: reads and writes (evidence: `backend-java/src/main/java/br/senai/ctiinsights/service/ClienteService.java`)
- Customer administration → Customer rules: delegates to (evidence: `backend-java/src/main/java/br/senai/ctiinsights/controller/ClienteController.java`)
- Dashboard endpoints → Dashboard services: delegates to (evidence: `backend-java/src/main/java/br/senai/ctiinsights/controller/DashboardController.java`)
- Customer repository → Customer records: stores entities (evidence: `backend-java/src/main/java/br/senai/ctiinsights/repository/ClienteRepository.java`)
- Customer records → PostgreSQL database: persisted in (evidence: `README.md`)
- CTI user → Authentication: authenticates with
- Python process runner → PostgreSQL database: feeds persisted results (evidence: `README.md`)
