# aditishosur/kyros-ai architecture

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

- Interactive diagram: https://gitdiagram.com/aditishosur/kyros-ai
- Repository: https://github.com/aditishosur/kyros-ai

## Overview

PulseOps is an API-operations intelligence platform. Its principal workflow is to inspect telemetry, forecast workload, detect anomalies, rank supported causes, and estimate scenario interventions; the Streamlit demo presents results through a FastAPI integration layer. The README also describes offline forecasting, anomaly, and scenario research. Research components are mapped to their documented directories; their detailed wiring is not established by the sampled source.

Main entry points: [`backend/main.py`](https://github.com/aditishosur/kyros-ai/blob/main/backend/main.py) (FastAPI routes), [`backend/database.py`](https://github.com/aditishosur/kyros-ai/blob/main/backend/database.py) (SQLite telemetry), [`backend/services/ml.py`](https://github.com/aditishosur/kyros-ai/blob/main/backend/services/ml.py) (Forecast and anomaly), [`backend/services/analytics.py`](https://github.com/aditishosur/kyros-ai/blob/main/backend/services/analytics.py) (Telemetry analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Demo interface"]
  node_streamlit["Streamlit demo<br/>[app.py]"]
  node_http_client["HTTP client<br/>[client.py]"]
end

subgraph group_api["API integration"]
  node_fastapi["FastAPI routes<br/>[main.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_intelligence["Operational intelligence"]
  node_analytics["Telemetry analytics<br/>[analytics.py]"]
  node_risk["Risk scoring<br/>[risk.py]"]
  node_forecast_detect["Forecast and anomaly<br/>[ml.py]"]
  node_diagnosis["Root-cause ranking<br/>[root_cause.py]"]
  node_simulation["Intervention simulation<br/>[simulation.py]"]
end

subgraph group_storage["Telemetry storage"]
  node_database[("SQLite telemetry<br/>[database.py]")]
  node_models["Persistence models<br/>[models.py]"]
  node_bootstrap["Database initialization<br/>[bootstrap.py]"]
end

subgraph group_research["Offline research"]
  node_telemetry_generator["Synthetic telemetry<br/>[generate_data.py]"]
  node_etl["Telemetry ETL demo<br/>[etl_pipeline.py]"]
  node_forecast_research["Forecast experiments"]
  node_anomaly_research["Anomaly evaluation"]
  node_scenario_research["Scenario generation"]
end

node_operator(("Operations user"))

node_operator -->|"uses"| node_streamlit
node_streamlit -->|"requests data"| node_http_client
node_http_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"validates payloads"| node_schemas
node_fastapi -->|"opens sessions"| node_database
node_fastapi -->|"initializes on startup"| node_bootstrap
node_bootstrap -->|"initializes store"| node_database
node_fastapi -->|"queries and updates"| node_models
node_fastapi -->|"calls analytics"| node_analytics
node_fastapi -->|"calls forecast and anomaly"| node_forecast_detect
node_fastapi -->|"calls diagnosis"| node_diagnosis
node_fastapi -->|"runs simulation"| node_simulation
node_analytics -->|"reads telemetry"| node_database
node_risk -->|"scores forecast risk"| node_forecast_detect
node_forecast_detect -->|"loads telemetry"| node_analytics
node_forecast_detect -->|"stores predictions"| node_database
node_diagnosis -->|"reads telemetry"| node_database
node_simulation -->|"reads telemetry"| node_database
node_telemetry_generator -.->|"generates input"| node_etl
node_etl -.->|"loads telemetry"| node_database
node_forecast_research -.-> node_anomaly_research
node_scenario_research -.->|"generates labeled episodes"| node_anomaly_research

click node_streamlit "https://github.com/aditishosur/kyros-ai/blob/main/frontend/app.py"
click node_http_client "https://github.com/aditishosur/kyros-ai/blob/main/frontend/client.py"
click node_fastapi "https://github.com/aditishosur/kyros-ai/blob/main/backend/main.py"
click node_schemas "https://github.com/aditishosur/kyros-ai/blob/main/backend/schemas.py"
click node_analytics "https://github.com/aditishosur/kyros-ai/blob/main/backend/services/analytics.py"
click node_risk "https://github.com/aditishosur/kyros-ai/blob/main/backend/services/risk.py"
click node_forecast_detect "https://github.com/aditishosur/kyros-ai/blob/main/backend/services/ml.py"
click node_diagnosis "https://github.com/aditishosur/kyros-ai/blob/main/backend/services/root_cause.py"
click node_simulation "https://github.com/aditishosur/kyros-ai/blob/main/backend/services/simulation.py"
click node_database "https://github.com/aditishosur/kyros-ai/blob/main/backend/database.py"
click node_models "https://github.com/aditishosur/kyros-ai/blob/main/backend/models.py"
click node_bootstrap "https://github.com/aditishosur/kyros-ai/blob/main/backend/bootstrap.py"
click node_telemetry_generator "https://github.com/aditishosur/kyros-ai/blob/main/data/generate_data.py"
click node_etl "https://github.com/aditishosur/kyros-ai/blob/main/extras/etl_pipeline.py"
click node_forecast_research "https://github.com/aditishosur/kyros-ai/tree/main/experiments/forecasting"
click node_anomaly_research "https://github.com/aditishosur/kyros-ai/tree/main/experiments/anomaly"
click node_scenario_research "https://github.com/aditishosur/kyros-ai/tree/main/experiments/scenarios"

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_streamlit,node_http_client,node_operator toneBlue
class node_fastapi,node_schemas toneAmber
class node_analytics,node_risk,node_forecast_detect,node_diagnosis,node_simulation toneMint
class node_database,node_models,node_bootstrap toneRose
class node_telemetry_generator,node_etl,node_forecast_research,node_anomaly_research,node_scenario_research toneIndigo
```

## Components

### Demo interface

- [Streamlit demo](https://github.com/aditishosur/kyros-ai/blob/main/frontend/app.py): `frontend/app.py`
- [HTTP client](https://github.com/aditishosur/kyros-ai/blob/main/frontend/client.py): `frontend/client.py`

### API integration

- [FastAPI routes](https://github.com/aditishosur/kyros-ai/blob/main/backend/main.py): `backend/main.py`
- [API schemas](https://github.com/aditishosur/kyros-ai/blob/main/backend/schemas.py): `backend/schemas.py`

### Operational intelligence

- [Telemetry analytics](https://github.com/aditishosur/kyros-ai/blob/main/backend/services/analytics.py): `backend/services/analytics.py`
- [Risk scoring](https://github.com/aditishosur/kyros-ai/blob/main/backend/services/risk.py): `backend/services/risk.py`
- [Forecast and anomaly](https://github.com/aditishosur/kyros-ai/blob/main/backend/services/ml.py): `backend/services/ml.py`
- [Root-cause ranking](https://github.com/aditishosur/kyros-ai/blob/main/backend/services/root_cause.py): `backend/services/root_cause.py`
- [Intervention simulation](https://github.com/aditishosur/kyros-ai/blob/main/backend/services/simulation.py): `backend/services/simulation.py`

### Telemetry storage

- [SQLite telemetry](https://github.com/aditishosur/kyros-ai/blob/main/backend/database.py): `backend/database.py`
- [Persistence models](https://github.com/aditishosur/kyros-ai/blob/main/backend/models.py): `backend/models.py`
- [Database initialization](https://github.com/aditishosur/kyros-ai/blob/main/backend/bootstrap.py): `backend/bootstrap.py`

### Offline research

- [Synthetic telemetry](https://github.com/aditishosur/kyros-ai/blob/main/data/generate_data.py): `data/generate_data.py`
- [Telemetry ETL demo](https://github.com/aditishosur/kyros-ai/blob/main/extras/etl_pipeline.py): `extras/etl_pipeline.py`
- [Forecast experiments](https://github.com/aditishosur/kyros-ai/tree/main/experiments/forecasting): `experiments/forecasting`
- [Anomaly evaluation](https://github.com/aditishosur/kyros-ai/tree/main/experiments/anomaly): `experiments/anomaly`
- [Scenario generation](https://github.com/aditishosur/kyros-ai/tree/main/experiments/scenarios): `experiments/scenarios`

### Other components

- **Operations user**

## Connections

- Operations user → Streamlit demo: uses
- Streamlit demo → HTTP client: requests data
- HTTP client → FastAPI routes: HTTP requests
- FastAPI routes → API schemas: validates payloads
- FastAPI routes → SQLite telemetry: opens sessions
- FastAPI routes → Database initialization: initializes on startup
- Database initialization → SQLite telemetry: initializes store
- FastAPI routes → Persistence models: queries and updates
- FastAPI routes → Telemetry analytics: calls analytics
- FastAPI routes → Forecast and anomaly: calls forecast and anomaly
- FastAPI routes → Root-cause ranking: calls diagnosis
- FastAPI routes → Intervention simulation: runs simulation
- Telemetry analytics → SQLite telemetry: reads telemetry
- Risk scoring → Forecast and anomaly: scores forecast risk
- Forecast and anomaly → Telemetry analytics: loads telemetry
- Forecast and anomaly → SQLite telemetry: stores predictions
- Root-cause ranking → SQLite telemetry: reads telemetry
- Intervention simulation → SQLite telemetry: reads telemetry
- Synthetic telemetry → Telemetry ETL demo: generates input
- Telemetry ETL demo → SQLite telemetry: loads telemetry
- Forecast experiments → Anomaly evaluation
- Scenario generation → Anomaly evaluation: generates labeled episodes