# lucaswbohrer/nexus architecture

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

- Interactive diagram: https://gitdiagram.com/lucaswbohrer/nexus
- Repository: https://github.com/lucaswbohrer/nexus

## Overview

NEXUS simulates electrical readings, analyzes them for anomalies, persists readings and generated events, and exposes current, diagnostic, history, and event data through a REST API for the monitoring dashboard. Simulation scenarios are configurable through an API endpoint. The dashboard excerpt shows current-reading, history, and event retrieval; it does not show dashboard controls for changing simulation mode. The graph follows documented capabilities and sampled call sites; unsampled subsystem wiring is omitted.

Main entry points: [`backend/app/api/routes.py`](https://github.com/lucaswbohrer/nexus/blob/main/backend/app/api/routes.py) (REST routes), [`backend/app/services/monitoring.py`](https://github.com/lucaswbohrer/nexus/blob/main/backend/app/services/monitoring.py) (Telemetry service), [`frontend/src/lib/api.ts`](https://github.com/lucaswbohrer/nexus/blob/main/frontend/src/lib/api.ts) (API client), [`frontend/src/app/page.tsx`](https://github.com/lucaswbohrer/nexus/blob/main/frontend/src/app/page.tsx) (Monitoring dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation"]
  node_simulator["Electrical simulator<br/>[simulator.py]"]
end

subgraph group_monitoring["Monitoring"]
  node_telemetry["Telemetry service<br/>[monitoring.py]"]
  node_diagnostics["Diagnostic engine<br/>[diagnostics.py]"]
  node_events["Monitoring events<br/>[events.py]"]
  node_database[("SQLite history<br/>[database.py]")]
end

subgraph group_backend["Backend API"]
  node_apiapp["FastAPI app<br/>[main.py]"]
  node_routes["REST routes<br/>[routes.py]"]
  node_schemas["Reading schema<br/>[schemas.py]"]
end

subgraph group_frontend["Dashboard"]
  node_api_client["API client<br/>[api.ts]"]
  node_dashboard["Monitoring dashboard<br/>[page.tsx]"]
  node_types["Monitoring types<br/>[monitoring.ts]"]
end

node_operator(("Operator"))

node_operator -->|"views"| node_dashboard
node_operator -->|"sets scenario"| node_routes
node_apiapp -->|"registers"| node_routes
node_apiapp -->|"initializes"| node_database
node_apiapp -->|"starts and stops"| node_telemetry
node_telemetry -->|"generates reading"| node_simulator
node_telemetry -->|"analyzes reading"| node_diagnostics
node_telemetry -->|"saves reading and events"| node_database
node_telemetry -->|"loads fallback reading"| node_database
node_diagnostics -->|"creates events"| node_events
node_routes -->|"gets current and diagnosis"| node_telemetry
node_routes -->|"gets history and events"| node_database
node_routes -->|"sets mode"| node_simulator
node_routes -->|"validates reading"| node_schemas
node_dashboard -->|"requests monitoring data"| node_api_client
node_api_client -->|"HTTP requests"| node_routes
node_routes -->|"returns API data"| node_api_client
node_api_client -->|"returns readings and events"| node_dashboard
node_dashboard -->|"uses data types"| node_types

click node_simulator "https://github.com/lucaswbohrer/nexus/blob/main/backend/app/engine/simulator.py"
click node_telemetry "https://github.com/lucaswbohrer/nexus/blob/main/backend/app/services/monitoring.py"
click node_diagnostics "https://github.com/lucaswbohrer/nexus/blob/main/backend/app/engine/diagnostics.py"
click node_events "https://github.com/lucaswbohrer/nexus/blob/main/backend/app/models/events.py"
click node_database "https://github.com/lucaswbohrer/nexus/blob/main/backend/app/database/database.py"
click node_apiapp "https://github.com/lucaswbohrer/nexus/blob/main/backend/app/main.py"
click node_routes "https://github.com/lucaswbohrer/nexus/blob/main/backend/app/api/routes.py"
click node_schemas "https://github.com/lucaswbohrer/nexus/blob/main/backend/app/models/schemas.py"
click node_api_client "https://github.com/lucaswbohrer/nexus/blob/main/frontend/src/lib/api.ts"
click node_dashboard "https://github.com/lucaswbohrer/nexus/blob/main/frontend/src/app/page.tsx"
click node_types "https://github.com/lucaswbohrer/nexus/blob/main/frontend/src/types/monitoring.ts"

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_simulator toneBlue
class node_telemetry,node_diagnostics,node_events,node_database toneAmber
class node_apiapp,node_routes,node_schemas toneMint
class node_api_client,node_dashboard,node_types toneRose
class node_operator toneIndigo
```

## Components

### Simulation

- [Electrical simulator](https://github.com/lucaswbohrer/nexus/blob/main/backend/app/engine/simulator.py): `backend/app/engine/simulator.py`

### Monitoring

- [Telemetry service](https://github.com/lucaswbohrer/nexus/blob/main/backend/app/services/monitoring.py): `backend/app/services/monitoring.py`
- [Diagnostic engine](https://github.com/lucaswbohrer/nexus/blob/main/backend/app/engine/diagnostics.py): `backend/app/engine/diagnostics.py`
- [Monitoring events](https://github.com/lucaswbohrer/nexus/blob/main/backend/app/models/events.py): `backend/app/models/events.py`
- [SQLite history](https://github.com/lucaswbohrer/nexus/blob/main/backend/app/database/database.py): `backend/app/database/database.py`

### Backend API

- [FastAPI app](https://github.com/lucaswbohrer/nexus/blob/main/backend/app/main.py): `backend/app/main.py`
- [REST routes](https://github.com/lucaswbohrer/nexus/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Reading schema](https://github.com/lucaswbohrer/nexus/blob/main/backend/app/models/schemas.py): `backend/app/models/schemas.py`

### Dashboard

- [API client](https://github.com/lucaswbohrer/nexus/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Monitoring dashboard](https://github.com/lucaswbohrer/nexus/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Monitoring types](https://github.com/lucaswbohrer/nexus/blob/main/frontend/src/types/monitoring.ts): `frontend/src/types/monitoring.ts`

### Other components

- **Operator**

## Connections

- Operator → Monitoring dashboard: views
- Operator → REST routes: sets scenario
- FastAPI app → REST routes: registers
- FastAPI app → SQLite history: initializes
- FastAPI app → Telemetry service: starts and stops
- Telemetry service → Electrical simulator: generates reading
- Telemetry service → Diagnostic engine: analyzes reading
- Telemetry service → SQLite history: saves reading and events
- Telemetry service → SQLite history: loads fallback reading
- Diagnostic engine → Monitoring events: creates events
- REST routes → Telemetry service: gets current and diagnosis
- REST routes → SQLite history: gets history and events
- REST routes → Electrical simulator: sets mode
- REST routes → Reading schema: validates reading
- Monitoring dashboard → API client: requests monitoring data
- API client → REST routes: HTTP requests
- REST routes → API client: returns API data
- API client → Monitoring dashboard: returns readings and events
- Monitoring dashboard → Monitoring types: uses data types