# spihar/caterpillarhackathon architecture

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

- Interactive diagram: https://gitdiagram.com/spihar/caterpillarhackathon
- Repository: https://github.com/spihar/caterpillarhackathon

## Overview

Smart Rental Intelligence is a dealer-facing equipment-rental and fleet-monitoring platform. A dealer logs in, views fleet and rental status in the dashboard, and can use the AI assistant; a separate telemetry client reports equipment readings to the API. The backend manages rental and fleet data, then derives alerts, demand forecasts, anomalies, and maintenance scores. The README documents QR check-in/out and other capabilities whose route implementations were not sampled; those are represented at their documented module boundaries. Arrows reflect sampled calls and documented telemetry flow.

Main entry points: [`backend/app/database.py`](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/database.py) (SQLite database), [`backend/app/main.py`](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/main.py) (FastAPI entry), [`frontend/src/pages/DashboardPage.tsx`](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/pages/DashboardPage.tsx) (Fleet dashboard), [`frontend/src/api.ts`](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/api.ts) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Dealer interface"]
  node_app["App routing<br/>[App.tsx]"]
  node_login["Login page<br/>[LoginPage.tsx]"]
  node_dashboard["Fleet dashboard<br/>[DashboardPage.tsx]"]
  node_fleet_views["Fleet views<br/>[FleetOverview.tsx]"]
  node_rental_view["Rental panel<br/>[RentalsPanel.tsx]"]
  node_alert_view["Alerts panel<br/>[AlertsPanel.tsx]"]
  node_forecast_view["Forecast panel<br/>[ForecastPanel.tsx]"]
  node_map_view["Asset map<br/>[AssetMap.tsx]"]
  node_chat_view["Agent chat<br/>[AgentChat.tsx]"]
  node_api_client["HTTP client<br/>[api.ts]"]
end

subgraph group_api["Rental platform API"]
  node_api_main["FastAPI entry<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_fleet_routes["Fleet and sites<br/>[equipment.py]"]
  node_rental_routes["Rental operations<br/>[rentals.py]"]
  node_dashboard_routes["Dashboard data<br/>[dashboard.py]"]
  node_telemetry_routes["Telemetry intake<br/>[telemetry.py]"]
  node_agent_route["Assistant endpoint<br/>[agent.py]"]
end

subgraph group_intelligence["Fleet intelligence"]
  node_simulator["Safety checks<br/>[simulator.py]"]
  node_telemetry_ingest["Telemetry processing"]
  node_alerts["Overdue alerts<br/>[alert_service.py]"]
  node_anomalies["Anomaly detection<br/>[anomaly_service.py]"]
  node_forecast["Demand forecast"]
  node_maintenance["Maintenance scoring"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_specialists["Specialist agents<br/>[specialists.py]"]
  node_agent_tools["Agent tools<br/>[tools.py]"]
end

subgraph group_state["Data and integrations"]
  node_database[("SQLite database<br/>[database.py]")]
  node_models["Domain models<br/>[models.py]"]
  node_telemetry_client["Telemetry client"]
end

node_dealer(("Dealer"))
node_groq{{"Groq LLM"}}

node_dealer -->|"uses"| node_app
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_dashboard
node_login -->|"submits login"| node_api_client
node_dashboard -->|"requests data"| node_api_client
node_dashboard -->|"renders"| node_fleet_views
node_dashboard -->|"renders"| node_rental_view
node_dashboard -->|"renders"| node_alert_view
node_dashboard -->|"renders"| node_forecast_view
node_dashboard -->|"renders"| node_map_view
node_dashboard -->|"renders"| node_chat_view
node_api_client -->|"calls"| node_auth
node_api_client -->|"calls"| node_fleet_routes
node_api_client -->|"calls"| node_rental_routes
node_api_client -->|"calls"| node_dashboard_routes
node_api_client -->|"calls"| node_agent_route
node_api_main -->|"registers"| node_auth
node_api_main -->|"registers"| node_fleet_routes
node_api_main -->|"registers"| node_rental_routes
node_api_main -->|"registers"| node_dashboard_routes
node_api_main -->|"registers"| node_telemetry_routes
node_api_main -->|"registers"| node_agent_route
node_api_main -->|"initializes"| node_database
node_api_main -->|"runs checks"| node_simulator
node_api_main -->|"runs forecast"| node_forecast
node_telemetry_client -->|"posts readings"| node_telemetry_routes
node_telemetry_routes -->|"passes readings"| node_telemetry_ingest
node_telemetry_ingest -->|"persists telemetry"| node_database
node_simulator -->|"checks returns"| node_alerts
node_simulator -->|"checks anomalies"| node_anomalies
node_simulator -->|"scores equipment"| node_maintenance
node_agent_route -->|"dispatches query"| node_orchestrator
node_orchestrator -->|"routes query"| node_specialists
node_specialists -->|"invokes tools"| node_agent_tools
node_orchestrator -->|"routes with LLM"| node_groq
node_agent_tools -->|"reads fleet data"| node_database
node_auth -->|"checks dealer"| node_database
node_fleet_routes -->|"reads and writes"| node_database
node_rental_routes -->|"reads and writes"| node_database
node_dashboard_routes -->|"reads summaries"| node_database
node_alerts -->|"stores notifications"| node_database
node_anomalies -->|"stores findings"| node_database
node_forecast -->|"stores forecasts"| node_database
node_maintenance -->|"stores alerts"| node_database
node_database -->|"maps records"| node_models

click node_app "https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/App.tsx"
click node_login "https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/pages/LoginPage.tsx"
click node_dashboard "https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/pages/DashboardPage.tsx"
click node_fleet_views "https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/FleetOverview.tsx"
click node_rental_view "https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/RentalsPanel.tsx"
click node_alert_view "https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/AlertsPanel.tsx"
click node_forecast_view "https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/ForecastPanel.tsx"
click node_map_view "https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/AssetMap.tsx"
click node_chat_view "https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/AgentChat.tsx"
click node_api_client "https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/api.ts"
click node_api_main "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/main.py"
click node_auth "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/auth.py"
click node_fleet_routes "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/equipment.py"
click node_rental_routes "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/rentals.py"
click node_dashboard_routes "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/dashboard.py"
click node_telemetry_routes "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/telemetry.py"
click node_agent_route "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/agent.py"
click node_simulator "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/simulator.py"
click node_telemetry_ingest "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/telemetry_ingest.py"
click node_alerts "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/alert_service.py"
click node_anomalies "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/anomaly_service.py"
click node_forecast "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/forecast_service.py"
click node_maintenance "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/maintenance_service.py"
click node_orchestrator "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/agents/orchestrator.py"
click node_specialists "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/agents/specialists.py"
click node_agent_tools "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/agents/tools.py"
click node_database "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/database.py"
click node_models "https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/models.py"
click node_telemetry_client "https://github.com/spihar/caterpillarhackathon/blob/master/backend/live_telemetry_client.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_login,node_dashboard,node_fleet_views,node_rental_view,node_alert_view,node_forecast_view,node_map_view,node_chat_view,node_api_client toneBlue
class node_api_main,node_auth,node_fleet_routes,node_rental_routes,node_dashboard_routes,node_telemetry_routes,node_agent_route toneAmber
class node_simulator,node_telemetry_ingest,node_alerts,node_anomalies,node_forecast,node_maintenance,node_orchestrator,node_specialists,node_agent_tools toneMint
class node_database,node_models,node_telemetry_client toneRose
class node_dealer,node_groq toneIndigo
```

## Components

### Dealer interface

- [App routing](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login page](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [Fleet dashboard](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Fleet views](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/FleetOverview.tsx): `frontend/src/components/FleetOverview.tsx`
- [Rental panel](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/RentalsPanel.tsx): `frontend/src/components/RentalsPanel.tsx`
- [Alerts panel](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/AlertsPanel.tsx): `frontend/src/components/AlertsPanel.tsx`
- [Forecast panel](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/ForecastPanel.tsx): `frontend/src/components/ForecastPanel.tsx`
- [Asset map](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/AssetMap.tsx): `frontend/src/components/AssetMap.tsx`
- [Agent chat](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/components/AgentChat.tsx): `frontend/src/components/AgentChat.tsx`
- [HTTP client](https://github.com/spihar/caterpillarhackathon/blob/master/frontend/src/api.ts): `frontend/src/api.ts`

### Rental platform API

- [FastAPI entry](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Fleet and sites](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/equipment.py): `backend/app/routers/equipment.py`
- [Rental operations](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/rentals.py): `backend/app/routers/rentals.py`
- [Dashboard data](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/dashboard.py): `backend/app/routers/dashboard.py`
- [Telemetry intake](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/telemetry.py): `backend/app/routers/telemetry.py`
- [Assistant endpoint](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/routers/agent.py): `backend/app/routers/agent.py`

### Fleet intelligence

- [Safety checks](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/simulator.py): `backend/app/services/simulator.py`
- [Telemetry processing](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/telemetry_ingest.py): `backend/app/services/telemetry_ingest.py`
- [Overdue alerts](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/alert_service.py): `backend/app/services/alert_service.py`
- [Anomaly detection](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/anomaly_service.py): `backend/app/services/anomaly_service.py`
- [Demand forecast](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/forecast_service.py): `backend/app/services/forecast_service.py`
- [Maintenance scoring](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/services/maintenance_service.py): `backend/app/services/maintenance_service.py`
- [Agent orchestrator](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/agents/orchestrator.py): `backend/app/agents/orchestrator.py`
- [Specialist agents](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/agents/specialists.py): `backend/app/agents/specialists.py`
- [Agent tools](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/agents/tools.py): `backend/app/agents/tools.py`

### Data and integrations

- [SQLite database](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/database.py): `backend/app/database.py`
- [Domain models](https://github.com/spihar/caterpillarhackathon/blob/master/backend/app/models.py): `backend/app/models.py`
- [Telemetry client](https://github.com/spihar/caterpillarhackathon/blob/master/backend/live_telemetry_client.py): `backend/live_telemetry_client.py`

### Other components

- **Dealer**
- **Groq LLM**

## Connections

- Dealer → App routing: uses
- App routing → Login page: routes to
- App routing → Fleet dashboard: routes to
- Login page → HTTP client: submits login
- Fleet dashboard → HTTP client: requests data
- Fleet dashboard → Fleet views: renders
- Fleet dashboard → Rental panel: renders
- Fleet dashboard → Alerts panel: renders
- Fleet dashboard → Forecast panel: renders
- Fleet dashboard → Asset map: renders
- Fleet dashboard → Agent chat: renders
- HTTP client → Authentication: calls
- HTTP client → Fleet and sites: calls
- HTTP client → Rental operations: calls
- HTTP client → Dashboard data: calls
- HTTP client → Assistant endpoint: calls
- FastAPI entry → Authentication: registers
- FastAPI entry → Fleet and sites: registers
- FastAPI entry → Rental operations: registers
- FastAPI entry → Dashboard data: registers
- FastAPI entry → Telemetry intake: registers
- FastAPI entry → Assistant endpoint: registers
- FastAPI entry → SQLite database: initializes
- FastAPI entry → Safety checks: runs checks
- FastAPI entry → Demand forecast: runs forecast
- Telemetry client → Telemetry intake: posts readings
- Telemetry intake → Telemetry processing: passes readings
- Telemetry processing → SQLite database: persists telemetry
- Safety checks → Overdue alerts: checks returns
- Safety checks → Anomaly detection: checks anomalies
- Safety checks → Maintenance scoring: scores equipment
- Assistant endpoint → Agent orchestrator: dispatches query
- Agent orchestrator → Specialist agents: routes query
- Specialist agents → Agent tools: invokes tools
- Agent orchestrator → Groq LLM: routes with LLM
- Agent tools → SQLite database: reads fleet data
- Authentication → SQLite database: checks dealer
- Fleet and sites → SQLite database: reads and writes
- Rental operations → SQLite database: reads and writes
- Dashboard data → SQLite database: reads summaries
- Overdue alerts → SQLite database: stores notifications
- Anomaly detection → SQLite database: stores findings
- Demand forecast → SQLite database: stores forecasts
- Maintenance scoring → SQLite database: stores alerts
- SQLite database → Domain models: maps records