# natanbarboza08/oversight architecture

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

## Overview

Oversight is a spreadsheet-based customer analytics application. A user uploads a spreadsheet through the Vue interface; the frontend validates rows, Java revalidates them and delegates valid rows to Python ETL, which cleans, analyzes, and persists results. Java serves persisted history and statistics for frontend reports and charts. Separate capabilities cover JWT authentication and administrator approval of accounts. The README documents cross-service and database flow; some internal wiring is supported by the source index, while unsampled modules are represented only where documented.

Main entry points: [`Frontend/src/services/api.js`](https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/services/api.js) (API client), [`analytics-python/main.py`](https://github.com/natanbarboza08/oversight/blob/main/analytics-python/main.py) (ETL endpoint), [`Backend/oversight/src/main/java/com/senai/oversight/service/AuthService.java`](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/AuthService.java) (Account authentication), [`Backend/oversight/src/main/java/com/senai/oversight/service/UploadService.java`](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/UploadService.java) (Batch validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Vue application"]
  node_upload_view["Upload screen<br/>[Upload.vue]"]
  node_upload_store["Sheet validation<br/>[uploadStore.js]"]
  node_auth_store["Session state<br/>[auth.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_reports["Reports and charts<br/>[Relatorios.vue]"]
  node_charts["Analytics charts<br/>[Graficos.vue]"]
end

subgraph group_java["Java API"]
  node_auth_controller["Authentication API"]
  node_auth_service["Account authentication<br/>[AuthService.java]"]
  node_jwt["JWT security<br/>[JwtService.java]"]
  node_admin_controller["User administration"]
  node_user_service["User management"]
  node_upload_controller["Upload API"]
  node_upload_service["Batch validation<br/>[UploadService.java]"]
  node_row_validator["Client row rules"]
  node_etl_client["ETL client"]
  node_dashboard["Dashboard queries"]
  node_user_repository["User repository"]
end

subgraph group_etl["Python analytics"]
  node_etl_api["ETL endpoint<br/>[main.py]"]
  node_cleaning["Data cleaning<br/>[limpeza.py]"]
  node_analysis["Metrics analysis<br/>[analise.py]"]
  node_insights["Insights<br/>[insights.py]"]
  node_python_store["ETL persistence<br/>[banco.py]"]
end

subgraph group_data["Persisted data"]
  node_postgres[("PostgreSQL")]
end

node_user(("User"))
node_admin(("Administrator"))

node_user -->|"uploads sheet"| node_upload_view
node_upload_view -->|"uses"| node_upload_store
node_upload_store -->|"sends valid rows"| node_api_client
node_api_client -->|"calls API"| node_upload_controller
node_upload_controller -.->|"delegates"| node_upload_service
node_upload_service -->|"validates rows"| node_row_validator
node_upload_service -->|"forwards valid batch"| node_etl_client
node_etl_client -->|"sends batch"| node_etl_api
node_etl_api -->|"cleans data"| node_cleaning
node_etl_api -->|"analyzes batch"| node_analysis
node_analysis -->|"uses cleaning"| node_cleaning
node_analysis -->|"uses insights"| node_insights
node_etl_api -->|"persists results"| node_python_store
node_python_store -->|"writes batch and metrics"| node_postgres
node_dashboard -->|"reads history and metrics"| node_postgres
node_api_client -.->|"serves reports"| node_reports
node_api_client -.->|"serves statistics"| node_charts
node_user -->|"registers or signs in"| node_auth_store
node_auth_store -->|"requests authentication"| node_api_client
node_api_client -->|"calls API"| node_auth_controller
node_auth_controller -->|"delegates"| node_auth_service
node_auth_service -->|"creates token"| node_jwt
node_auth_service -->|"saves or finds users"| node_user_repository
node_user_repository -->|"stores accounts"| node_postgres
node_admin -->|"manages accounts"| node_admin_controller
node_admin_controller -->|"delegates"| node_user_service
node_user_service -->|"updates accounts"| node_user_repository

click node_upload_view "https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/views/Upload.vue"
click node_upload_store "https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/stores/uploadStore.js"
click node_auth_store "https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/stores/auth.js"
click node_api_client "https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/services/api.js"
click node_reports "https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/views/Relatorios.vue"
click node_charts "https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/views/Graficos.vue"
click node_auth_controller "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/controller/AuthController.java"
click node_auth_service "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/AuthService.java"
click node_jwt "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/config/JwtService.java"
click node_admin_controller "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/controller/AdminUsuarioController.java"
click node_user_service "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/UsuarioService.java"
click node_upload_controller "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/controller/UploadController.java"
click node_upload_service "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/UploadService.java"
click node_row_validator "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/ClienteValidacaoService.java"
click node_etl_client "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/PythonEtlService.java"
click node_dashboard "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/DashboardService.java"
click node_etl_api "https://github.com/natanbarboza08/oversight/blob/main/analytics-python/main.py"
click node_cleaning "https://github.com/natanbarboza08/oversight/blob/main/analytics-python/limpeza.py"
click node_analysis "https://github.com/natanbarboza08/oversight/blob/main/analytics-python/analise.py"
click node_insights "https://github.com/natanbarboza08/oversight/blob/main/analytics-python/insights.py"
click node_python_store "https://github.com/natanbarboza08/oversight/blob/main/analytics-python/banco.py"
click node_user_repository "https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/repository/UsuarioRepository.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_upload_view,node_upload_store,node_auth_store,node_api_client,node_reports,node_charts,node_user toneBlue
class node_auth_controller,node_auth_service,node_jwt,node_admin_controller,node_user_service,node_upload_controller,node_upload_service,node_row_validator,node_etl_client,node_dashboard,node_user_repository toneAmber
class node_etl_api,node_cleaning,node_analysis,node_insights,node_python_store toneMint
class node_postgres toneRose
class node_admin toneIndigo
```

## Components

### Vue application

- [Upload screen](https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/views/Upload.vue): `Frontend/src/views/Upload.vue`
- [Sheet validation](https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/stores/uploadStore.js): `Frontend/src/stores/uploadStore.js`
- [Session state](https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/stores/auth.js): `Frontend/src/stores/auth.js`
- [API client](https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/services/api.js): `Frontend/src/services/api.js`
- [Reports and charts](https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/views/Relatorios.vue): `Frontend/src/views/Relatorios.vue`
- [Analytics charts](https://github.com/natanbarboza08/oversight/blob/main/Frontend/src/views/Graficos.vue): `Frontend/src/views/Graficos.vue`

### Java API

- [Authentication API](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/controller/AuthController.java): `Backend/oversight/src/main/java/com/senai/oversight/controller/AuthController.java`
- [Account authentication](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/AuthService.java): `Backend/oversight/src/main/java/com/senai/oversight/service/AuthService.java`
- [JWT security](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/config/JwtService.java): `Backend/oversight/src/main/java/com/senai/oversight/config/JwtService.java`
- [User administration](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/controller/AdminUsuarioController.java): `Backend/oversight/src/main/java/com/senai/oversight/controller/AdminUsuarioController.java`
- [User management](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/UsuarioService.java): `Backend/oversight/src/main/java/com/senai/oversight/service/UsuarioService.java`
- [Upload API](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/controller/UploadController.java): `Backend/oversight/src/main/java/com/senai/oversight/controller/UploadController.java`
- [Batch validation](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/UploadService.java): `Backend/oversight/src/main/java/com/senai/oversight/service/UploadService.java`
- [Client row rules](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/ClienteValidacaoService.java): `Backend/oversight/src/main/java/com/senai/oversight/service/ClienteValidacaoService.java`
- [ETL client](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/PythonEtlService.java): `Backend/oversight/src/main/java/com/senai/oversight/service/PythonEtlService.java`
- [Dashboard queries](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/service/DashboardService.java): `Backend/oversight/src/main/java/com/senai/oversight/service/DashboardService.java`
- [User repository](https://github.com/natanbarboza08/oversight/blob/main/Backend/oversight/src/main/java/com/senai/oversight/repository/UsuarioRepository.java): `Backend/oversight/src/main/java/com/senai/oversight/repository/UsuarioRepository.java`

### Python analytics

- [ETL endpoint](https://github.com/natanbarboza08/oversight/blob/main/analytics-python/main.py): `analytics-python/main.py`
- [Data cleaning](https://github.com/natanbarboza08/oversight/blob/main/analytics-python/limpeza.py): `analytics-python/limpeza.py`
- [Metrics analysis](https://github.com/natanbarboza08/oversight/blob/main/analytics-python/analise.py): `analytics-python/analise.py`
- [Insights](https://github.com/natanbarboza08/oversight/blob/main/analytics-python/insights.py): `analytics-python/insights.py`
- [ETL persistence](https://github.com/natanbarboza08/oversight/blob/main/analytics-python/banco.py): `analytics-python/banco.py`

### Persisted data

- **PostgreSQL**

### Other components

- **User**
- **Administrator**

## Connections

- User → Upload screen: uploads sheet
- Upload screen → Sheet validation: uses (evidence: `Frontend/src/views/Upload.vue`)
- Sheet validation → API client: sends valid rows (evidence: `Frontend/src/stores/uploadStore.js`)
- API client → Upload API: calls API
- Upload API → Batch validation: delegates
- Batch validation → Client row rules: validates rows (evidence: `Backend/oversight/src/main/java/com/senai/oversight/service/UploadService.java`)
- Batch validation → ETL client: forwards valid batch (evidence: `Backend/oversight/src/main/java/com/senai/oversight/service/UploadService.java`)
- ETL client → ETL endpoint: sends batch
- ETL endpoint → Data cleaning: cleans data (evidence: `analytics-python/main.py`)
- ETL endpoint → Metrics analysis: analyzes batch (evidence: `analytics-python/main.py`)
- Metrics analysis → Data cleaning: uses cleaning (evidence: `analytics-python/analise.py`)
- Metrics analysis → Insights: uses insights (evidence: `analytics-python/analise.py`)
- ETL endpoint → ETL persistence: persists results (evidence: `analytics-python/main.py`)
- ETL persistence → PostgreSQL: writes batch and metrics
- Dashboard queries → PostgreSQL: reads history and metrics
- API client → Reports and charts: serves reports
- API client → Analytics charts: serves statistics
- User → Session state: registers or signs in
- Session state → API client: requests authentication (evidence: `Frontend/src/stores/auth.js`)
- API client → Authentication API: calls API
- Authentication API → Account authentication: delegates (evidence: `Backend/oversight/src/main/java/com/senai/oversight/controller/AuthController.java`)
- Account authentication → JWT security: creates token (evidence: `Backend/oversight/src/main/java/com/senai/oversight/service/AuthService.java`)
- Account authentication → User repository: saves or finds users (evidence: `Backend/oversight/src/main/java/com/senai/oversight/service/AuthService.java`)
- User repository → PostgreSQL: stores accounts
- Administrator → User administration: manages accounts
- User administration → User management: delegates (evidence: `Backend/oversight/src/main/java/com/senai/oversight/controller/AdminUsuarioController.java`)
- User management → User repository: updates accounts (evidence: `Backend/oversight/src/main/java/com/senai/oversight/service/UsuarioService.java`)
