# martinherreraramirez/trackpredict-secure architecture

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

- Interactive diagram: https://gitdiagram.com/martinherreraramirez/trackpredict-secure
- Repository: https://github.com/martinherreraramirez/trackpredict-secure

## Overview

TrackPredict Secure monitors security fleets, ingesting GPS positions and presenting live fleet status, alerts, trip management, ETA and route-anomaly predictions, model metrics, administration, and audit history. The main path is simulated device → authenticated Java ingestion and business rules → PostgreSQL/PostGIS; React users access Java APIs, while Java alone calls the private FastAPI analytics service. The graph also preserves registration, trip planning, geofences, retraining, and role-based access. Internal call links are shown only where excerpts or the source index support them; documented service boundaries use README evidence.

Main entry points: [`frontend/src/components/Dashboard.tsx`](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/components/Dashboard.tsx) (Fleet dashboard), [`frontend/src/api.ts`](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/api.ts) (API client), [`backend-java/src/main/java/com/trackpredict/service/ViajeAnalisisService.java`](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/ViajeAnalisisService.java) (Trip analysis), [`analytics-python/app/main.py`](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/analytics-python/app/main.py) (FastAPI analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and UI"]
  node_app["Session shell<br/>[App.tsx]"]
  node_dashboard["Fleet dashboard<br/>[Dashboard.tsx]"]
  node_api["API client<br/>[api.ts]"]
  node_tripui["Trip panel<br/>[PanelViajes.tsx]"]
  node_modelui["Model panel<br/>[PanelModelos.tsx]"]
  node_roles["Role permissions<br/>[permisos.ts]"]
end

subgraph group_core["Java business API"]
  node_authcontroller["Auth endpoints"]
  node_tripcontroller["Trip endpoints"]
  node_analyticscontroller["Prediction endpoints"]
  node_positioncontroller["Position ingestion"]
  node_alertservice["Alert rules<br/>[AlertaService.java]"]
  node_tripanalysis["Trip analysis"]
  node_retraining["Model retraining"]
  node_analyticsclient["Analytics client"]
end

subgraph group_data["Fleet state"]
  node_georepo["Geospatial queries<br/>[GeoRepository.java]"]
  node_database[("PostgreSQL/PostGIS")]
end

subgraph group_analytics["Predictive analytics"]
  node_python["FastAPI analytics<br/>[main.py]"]
  node_geo["Route geometry<br/>[geo.py]"]
  node_synthetic["Synthetic data<br/>[synthetic.py]"]
end

subgraph group_security["Identity and audit"]
  node_audit["Audit service"]
  node_registration["Tenant registration"]
  node_jwt["JWT service<br/>[JwtService.java]"]
end

node_operator(("Fleet user"))
node_simulator["GPS simulator<br/>[simulator.py]"]

node_operator -->|"uses"| node_app
node_app -->|"opens"| node_dashboard
node_dashboard -->|"requests data"| node_api
node_dashboard -->|"renders"| node_tripui
node_dashboard -->|"renders"| node_modelui
node_dashboard -->|"checks access"| node_roles
node_api -->|"calls auth API"| node_authcontroller
node_api -->|"calls trip API"| node_tripcontroller
node_api -->|"calls prediction API"| node_analyticscontroller
node_simulator -->|"sends GPS"| node_positioncontroller
node_positioncontroller -.->|"evaluates positions"| node_alertservice
node_tripcontroller -->|"requests analysis"| node_tripanalysis
node_tripanalysis -->|"requests predictions"| node_analyticsclient
node_analyticsclient -->|"REST calls"| node_python
node_python -->|"uses geometry"| node_geo
node_python -->|"uses synthetic data"| node_synthetic
node_tripanalysis -->|"reads route geometry"| node_georepo
node_alertservice -->|"checks geofence"| node_georepo
node_georepo -->|"queries spatial data"| node_database
node_registration -->|"records registration"| node_audit
node_registration -->|"creates tenant"| node_database
node_audit -->|"writes and reads"| node_database
node_authcontroller -->|"issues tokens"| node_jwt
node_retraining -->|"requests retraining"| node_analyticsclient

click node_simulator "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/simulator/simulator.py"
click node_app "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/components/Dashboard.tsx"
click node_api "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/api.ts"
click node_tripui "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/components/PanelViajes.tsx"
click node_modelui "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/components/PanelModelos.tsx"
click node_roles "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/permisos.ts"
click node_authcontroller "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/web/AuthController.java"
click node_tripcontroller "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/web/ViajeController.java"
click node_analyticscontroller "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/web/PrediccionController.java"
click node_positioncontroller "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/web/PosicionController.java"
click node_alertservice "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/AlertaService.java"
click node_tripanalysis "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/ViajeAnalisisService.java"
click node_retraining "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/ReentrenamientoService.java"
click node_analyticsclient "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/AnalyticsClient.java"
click node_georepo "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/repository/GeoRepository.java"
click node_audit "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/AuditoriaService.java"
click node_registration "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/RegistroService.java"
click node_jwt "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/security/JwtService.java"
click node_python "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/analytics-python/app/main.py"
click node_geo "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/analytics-python/app/geo.py"
click node_synthetic "https://github.com/martinherreraramirez/trackpredict-secure/blob/main/analytics-python/app/synthetic.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_app,node_dashboard,node_api,node_tripui,node_modelui,node_roles,node_operator toneBlue
class node_authcontroller,node_tripcontroller,node_analyticscontroller,node_positioncontroller,node_alertservice,node_tripanalysis,node_retraining,node_analyticsclient toneAmber
class node_georepo,node_database toneMint
class node_python,node_geo,node_synthetic toneRose
class node_audit,node_registration,node_jwt toneIndigo
class node_simulator toneTeal
```

## Components

### Clients and UI

- [Session shell](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Fleet dashboard](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/components/Dashboard.tsx): `frontend/src/components/Dashboard.tsx`
- [API client](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Trip panel](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/components/PanelViajes.tsx): `frontend/src/components/PanelViajes.tsx`
- [Model panel](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/components/PanelModelos.tsx): `frontend/src/components/PanelModelos.tsx`
- [Role permissions](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/frontend/src/permisos.ts): `frontend/src/permisos.ts`

### Java business API

- [Auth endpoints](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/web/AuthController.java): `backend-java/src/main/java/com/trackpredict/web/AuthController.java`
- [Trip endpoints](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/web/ViajeController.java): `backend-java/src/main/java/com/trackpredict/web/ViajeController.java`
- [Prediction endpoints](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/web/PrediccionController.java): `backend-java/src/main/java/com/trackpredict/web/PrediccionController.java`
- [Position ingestion](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/web/PosicionController.java): `backend-java/src/main/java/com/trackpredict/web/PosicionController.java`
- [Alert rules](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/AlertaService.java): `backend-java/src/main/java/com/trackpredict/service/AlertaService.java`
- [Trip analysis](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/ViajeAnalisisService.java): `backend-java/src/main/java/com/trackpredict/service/ViajeAnalisisService.java`
- [Model retraining](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/ReentrenamientoService.java): `backend-java/src/main/java/com/trackpredict/service/ReentrenamientoService.java`
- [Analytics client](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/AnalyticsClient.java): `backend-java/src/main/java/com/trackpredict/service/AnalyticsClient.java`

### Fleet state

- [Geospatial queries](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/repository/GeoRepository.java): `backend-java/src/main/java/com/trackpredict/repository/GeoRepository.java`
- **PostgreSQL/PostGIS**

### Predictive analytics

- [FastAPI analytics](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/analytics-python/app/main.py): `analytics-python/app/main.py`
- [Route geometry](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/analytics-python/app/geo.py): `analytics-python/app/geo.py`
- [Synthetic data](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/analytics-python/app/synthetic.py): `analytics-python/app/synthetic.py`

### Identity and audit

- [Audit service](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/AuditoriaService.java): `backend-java/src/main/java/com/trackpredict/service/AuditoriaService.java`
- [Tenant registration](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/service/RegistroService.java): `backend-java/src/main/java/com/trackpredict/service/RegistroService.java`
- [JWT service](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/backend-java/src/main/java/com/trackpredict/security/JwtService.java): `backend-java/src/main/java/com/trackpredict/security/JwtService.java`

### Other components

- **Fleet user**
- [GPS simulator](https://github.com/martinherreraramirez/trackpredict-secure/blob/main/simulator/simulator.py): `simulator/simulator.py`

## Connections

- Fleet user → Session shell: uses (evidence: `README.md`)
- Session shell → Fleet dashboard: opens (evidence: `frontend/src/App.tsx`)
- Fleet dashboard → API client: requests data (evidence: `frontend/src/components/Dashboard.tsx`)
- Fleet dashboard → Trip panel: renders (evidence: `frontend/src/components/Dashboard.tsx`)
- Fleet dashboard → Model panel: renders (evidence: `frontend/src/components/Dashboard.tsx`)
- Fleet dashboard → Role permissions: checks access (evidence: `frontend/src/components/Dashboard.tsx`)
- API client → Auth endpoints: calls auth API (evidence: `frontend/src/api.ts`)
- API client → Trip endpoints: calls trip API (evidence: `frontend/src/api.ts`)
- API client → Prediction endpoints: calls prediction API (evidence: `frontend/src/api.ts`)
- GPS simulator → Position ingestion: sends GPS (evidence: `README.md`)
- Position ingestion → Alert rules: evaluates positions
- Trip endpoints → Trip analysis: requests analysis (evidence: `backend-java/src/main/java/com/trackpredict/web/ViajeController.java`)
- Trip analysis → Analytics client: requests predictions (evidence: `backend-java/src/main/java/com/trackpredict/service/ViajeAnalisisService.java`)
- Analytics client → FastAPI analytics: REST calls (evidence: `README.md`)
- FastAPI analytics → Route geometry: uses geometry (evidence: `analytics-python/app/main.py`)
- FastAPI analytics → Synthetic data: uses synthetic data (evidence: `analytics-python/app/main.py`)
- Trip analysis → Geospatial queries: reads route geometry (evidence: `backend-java/src/main/java/com/trackpredict/service/ViajeAnalisisService.java`)
- Alert rules → Geospatial queries: checks geofence (evidence: `backend-java/src/main/java/com/trackpredict/service/AlertaService.java`)
- Geospatial queries → PostgreSQL/PostGIS: queries spatial data (evidence: `backend-java/src/main/java/com/trackpredict/repository/GeoRepository.java`)
- Tenant registration → Audit service: records registration (evidence: `backend-java/src/main/java/com/trackpredict/service/RegistroService.java`)
- Tenant registration → PostgreSQL/PostGIS: creates tenant (evidence: `backend-java/src/main/java/com/trackpredict/service/RegistroService.java`)
- Audit service → PostgreSQL/PostGIS: writes and reads (evidence: `backend-java/src/main/java/com/trackpredict/service/AuditoriaService.java`)
- Auth endpoints → JWT service: issues tokens (evidence: `backend-java/src/main/java/com/trackpredict/web/AuthController.java`)
- Model retraining → Analytics client: requests retraining (evidence: `backend-java/src/main/java/com/trackpredict/service/ReentrenamientoService.java`)