# samsraina/bob-ai-hackathon-cyber-elevate architecture

> Architecture diagram of the GitHub repository samsraina/bob-ai-hackathon-cyber-elevate, 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/samsraina/bob-ai-hackathon-cyber-elevate
- Repository: https://github.com/samsraina/bob-ai-hackathon-cyber-elevate

## Overview

Bob Engine is a FIR intelligence application: users explore FIRs and related suspects, review cross-district offender patterns and explanations, and inspect crime geography and alerts. The sampled REST routes delegate scoped queries to a shared intelligence service backed by PostgreSQL; the web app presents dashboard, FIR, offender, graph, map, and alert views. The README documents entity resolution, MO-similarity clustering, and automatic pattern alerts, but their internal wiring is not established by the sampled engine source, so those links are left out.

Main entry points: [`src/app/services/intelligence.py`](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/services/intelligence.py) (Intelligence service), [`src/app/core/database.py`](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/core/database.py) (Database sessions), [`src/app/main.py`](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/main.py) (FastAPI application), [`src/app/api/routes_firs.py`](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/api/routes_firs.py) (FIR routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_web_app["Application shell<br/>[App.tsx]"]
  node_web_client["API client<br/>[client.ts]"]
  node_web_views["Intelligence views"]
end

subgraph group_api["REST API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_fir_routes["FIR routes<br/>[routes_firs.py]"]
  node_intelligence_routes["Intelligence routes<br/>[routes_rest.py]"]
  node_alert_routes["Alert routes<br/>[routes_alerts.py]"]
end

subgraph group_services["Intelligence services"]
  node_intelligence_service["Intelligence service<br/>[intelligence.py]"]
end

subgraph group_engine["Analysis engine"]
  node_entity_resolution["Entity resolution"]
  node_mo_similarity["MO similarity<br/>[mo_similarity.py]"]
  node_pattern_alerts["Pattern alerts<br/>[pattern_alerts.py]"]
  node_graph_builder["Graph builder<br/>[graph_builder.py]"]
  node_geo_aggregation["Geo aggregation<br/>[geo_aggregation.py]"]
  node_llm_client["Reasoning gloss<br/>[llm_client.py]"]
end

subgraph group_data["Data and access"]
  node_rbac["Scope and RBAC<br/>[rbac.py]"]
  node_db_session["Database sessions<br/>[database.py]"]
  node_fir_models["FIR and cluster models<br/>[fir_models.py]"]
end

node_analyst(("Analyst"))
node_llm_service{{"LLM service"}}
node_postgres[("PostgreSQL")]

node_analyst -->|"uses"| node_web_app
node_web_app -->|"routes to"| node_web_views
node_web_views -->|"requests data"| node_web_client
node_web_client -->|"fetches"| node_api_app
node_api_app -->|"dispatches"| node_fir_routes
node_api_app -->|"dispatches"| node_intelligence_routes
node_api_app -->|"dispatches"| node_alert_routes
node_fir_routes -->|"calls"| node_intelligence_service
node_intelligence_routes -->|"calls"| node_intelligence_service
node_alert_routes -->|"calls"| node_intelligence_service
node_fir_routes -->|"resolves scope"| node_rbac
node_intelligence_routes -->|"resolves scope"| node_rbac
node_alert_routes -->|"resolves scope"| node_rbac
node_fir_routes -->|"gets session"| node_db_session
node_intelligence_routes -->|"gets session"| node_db_session
node_alert_routes -->|"gets session"| node_db_session
node_intelligence_service -->|"queries"| node_db_session
node_db_session -->|"reads and writes"| node_postgres
node_db_session -->|"registers models"| node_fir_models
node_intelligence_service -->|"builds graph"| node_graph_builder
node_intelligence_service -->|"computes map data"| node_geo_aggregation
node_llm_client -.->|"requests explanation"| node_llm_service

click node_web_app "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/web/src/App.tsx"
click node_web_client "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/web/src/api/client.ts"
click node_web_views "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/tree/main/src/web/src/routes"
click node_api_app "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/main.py"
click node_fir_routes "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/api/routes_firs.py"
click node_intelligence_routes "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/api/routes_rest.py"
click node_alert_routes "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/api/routes_alerts.py"
click node_intelligence_service "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/services/intelligence.py"
click node_entity_resolution "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/entity_resolution.py"
click node_mo_similarity "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/mo_similarity.py"
click node_pattern_alerts "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/pattern_alerts.py"
click node_graph_builder "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/graph_builder.py"
click node_geo_aggregation "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/geo_aggregation.py"
click node_llm_client "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/llm_client.py"
click node_rbac "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/core/rbac.py"
click node_db_session "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/core/database.py"
click node_fir_models "https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/models/fir_models.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_web_app,node_web_client,node_web_views toneBlue
class node_api_app,node_fir_routes,node_intelligence_routes,node_alert_routes,node_postgres toneAmber
class node_intelligence_service toneMint
class node_entity_resolution,node_mo_similarity,node_pattern_alerts,node_graph_builder,node_geo_aggregation,node_llm_client toneRose
class node_rbac,node_db_session,node_fir_models,node_analyst,node_llm_service toneIndigo
```

## Components

### Web application

- [Application shell](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/web/src/App.tsx): `src/web/src/App.tsx`
- [API client](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/web/src/api/client.ts): `src/web/src/api/client.ts`
- [Intelligence views](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/tree/main/src/web/src/routes): `src/web/src/routes`

### REST API

- [FastAPI application](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/main.py): `src/app/main.py`
- [FIR routes](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/api/routes_firs.py): `src/app/api/routes_firs.py`
- [Intelligence routes](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/api/routes_rest.py): `src/app/api/routes_rest.py`
- [Alert routes](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/api/routes_alerts.py): `src/app/api/routes_alerts.py`

### Intelligence services

- [Intelligence service](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/services/intelligence.py): `src/app/services/intelligence.py`

### Analysis engine

- [Entity resolution](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/entity_resolution.py): `src/app/engine/entity_resolution.py`
- [MO similarity](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/mo_similarity.py): `src/app/engine/mo_similarity.py`
- [Pattern alerts](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/pattern_alerts.py): `src/app/engine/pattern_alerts.py`
- [Graph builder](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/graph_builder.py): `src/app/engine/graph_builder.py`
- [Geo aggregation](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/geo_aggregation.py): `src/app/engine/geo_aggregation.py`
- [Reasoning gloss](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/engine/llm_client.py): `src/app/engine/llm_client.py`

### Data and access

- [Scope and RBAC](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/core/rbac.py): `src/app/core/rbac.py`
- [Database sessions](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/core/database.py): `src/app/core/database.py`
- [FIR and cluster models](https://github.com/samsraina/bob-ai-hackathon-cyber-elevate/blob/main/src/app/models/fir_models.py): `src/app/models/fir_models.py`

### Other components

- **Analyst**
- **LLM service**
- **PostgreSQL**

## Connections

- Analyst → Application shell: uses
- Application shell → Intelligence views: routes to
- Intelligence views → API client: requests data
- API client → FastAPI application: fetches
- FastAPI application → FIR routes: dispatches
- FastAPI application → Intelligence routes: dispatches
- FastAPI application → Alert routes: dispatches
- FIR routes → Intelligence service: calls
- Intelligence routes → Intelligence service: calls
- Alert routes → Intelligence service: calls
- FIR routes → Scope and RBAC: resolves scope
- Intelligence routes → Scope and RBAC: resolves scope
- Alert routes → Scope and RBAC: resolves scope
- FIR routes → Database sessions: gets session
- Intelligence routes → Database sessions: gets session
- Alert routes → Database sessions: gets session
- Intelligence service → Database sessions: queries
- Database sessions → PostgreSQL: reads and writes
- Database sessions → FIR and cluster models: registers models
- Intelligence service → Graph builder: builds graph
- Intelligence service → Geo aggregation: computes map data
- Reasoning gloss → LLM service: requests explanation