# mehulp007/criciq architecture

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

- Interactive diagram: https://gitdiagram.com/mehulp007/criciq
- Repository: https://github.com/mehulp007/criciq

## Overview

CricIQ is an IPL cricket intelligence platform: ball-by-ball data is prepared and scored, then served through an API to interactive web analytics and simulations. The graph preserves the documented data, model, and user-facing capability branches. Some subsystem connections are documented only in the README; unsampled implementation details and their internal call paths are not inferred.

Main entry points: [`pipelines/src/criciq_pipelines/pipeline.py`](https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/pipeline.py) (Data pipeline), [`frontend/app`](https://github.com/mehulp007/criciq/tree/main/frontend/app) (Next.js pages), [`pipelines/src/criciq_pipelines/warehouse.py`](https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/warehouse.py) (Analytics warehouse), [`backend/src/criciq_api/db.py`](https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/db.py) (Serving database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_pipeline["Data pipeline<br/>[pipeline.py]"]
  node_extract["Ball extraction<br/>[extract.py]"]
  node_warehouse[("Analytics warehouse<br/>[warehouse.py]")]
  node_validation["Data validation<br/>[validation.py]"]
  node_serving_export["Serving export<br/>[export.py]"]
end

subgraph group_models["Models and research"]
  node_ml_scoring["Model scoring<br/>[ball_outcome.py]"]
  node_analytics_lab["Analytics Lab<br/>[lab.py]"]
end

subgraph group_backend["Serving API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_routes["API routes<br/>[router.py]"]
  node_api_services["Domain services"]
  node_api_repositories["Query repositories"]
  node_serving_db[("Serving database<br/>[db.py]")]
end

subgraph group_web["Web experience"]
  node_web_app["Next.js pages"]
  node_api_client["API client<br/>[client.ts]"]
  node_replay["Match replay<br/>[engine.ts]"]
  node_web_sim_routes["Simulation routes<br/>[route.ts]"]
end

subgraph group_simulation["Simulation"]
  node_core_sim["Simulation engine<br/>[simulation.py]"]
  node_sim_service["Simulation service<br/>[simulation.py]"]
  node_sim_repository["Simulation queries<br/>[simulation.py]"]
end

node_user(("Cricket analyst"))
node_cricsheet["Cricsheet data"]

node_user -->|"explores analytics"| node_web_app
node_cricsheet -->|"supplies ball data"| node_extract
node_pipeline -->|"runs extraction"| node_extract
node_pipeline -->|"builds warehouse"| node_warehouse
node_pipeline -->|"validates data"| node_validation
node_pipeline -->|"exports serving data"| node_serving_export
node_pipeline -->|"reads and writes"| node_warehouse
node_warehouse -->|"provides model data"| node_ml_scoring
node_ml_scoring -->|"publishes predictions"| node_serving_db
node_warehouse -->|"exports database"| node_serving_export
node_serving_db -->|"opens serving data"| node_api_app
node_api_app -->|"mounts routes"| node_api_routes
node_api_routes -.->|"dispatches requests"| node_api_services
node_api_services -.->|"queries data"| node_api_repositories
node_api_repositories -.->|"reads data"| node_serving_db
node_web_app -->|"requests analytics"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_web_app -->|"replays matches"| node_replay
node_web_app -->|"offers simulation"| node_web_sim_routes
node_web_sim_routes -.->|"submits simulation"| node_sim_service
node_sim_service -->|"loads simulation data"| node_sim_repository
node_sim_service -->|"runs simulation"| node_core_sim
node_analytics_lab -->|"analyzes scored data"| node_serving_db

click node_pipeline "https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/pipeline.py"
click node_extract "https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/extract.py"
click node_warehouse "https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/warehouse.py"
click node_validation "https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/validation.py"
click node_serving_export "https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/export.py"
click node_ml_scoring "https://github.com/mehulp007/criciq/blob/main/ml/src/criciq_ml/ball_outcome.py"
click node_analytics_lab "https://github.com/mehulp007/criciq/blob/main/ml/src/criciq_ml/lab.py"
click node_api_app "https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/main.py"
click node_api_routes "https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/api/v1/router.py"
click node_api_services "https://github.com/mehulp007/criciq/tree/main/backend/src/criciq_api/services"
click node_api_repositories "https://github.com/mehulp007/criciq/tree/main/backend/src/criciq_api/repositories"
click node_serving_db "https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/db.py"
click node_web_app "https://github.com/mehulp007/criciq/tree/main/frontend/app"
click node_api_client "https://github.com/mehulp007/criciq/blob/main/frontend/lib/api/client.ts"
click node_replay "https://github.com/mehulp007/criciq/blob/main/frontend/lib/replay/engine.ts"
click node_web_sim_routes "https://github.com/mehulp007/criciq/blob/main/frontend/app/api/simulate/match/route.ts"
click node_core_sim "https://github.com/mehulp007/criciq/blob/main/core/src/criciq_core/simulation.py"
click node_sim_service "https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/services/simulation.py"
click node_sim_repository "https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/repositories/simulation.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_pipeline,node_extract,node_warehouse,node_validation,node_serving_export toneBlue
class node_ml_scoring,node_analytics_lab toneAmber
class node_api_app,node_api_routes,node_api_services,node_api_repositories,node_serving_db toneMint
class node_web_app,node_api_client,node_replay,node_web_sim_routes toneRose
class node_core_sim,node_sim_service,node_sim_repository,node_user,node_cricsheet toneIndigo
```

## Components

### Data preparation

- [Data pipeline](https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/pipeline.py): `pipelines/src/criciq_pipelines/pipeline.py`
- [Ball extraction](https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/extract.py): `pipelines/src/criciq_pipelines/extract.py`
- [Analytics warehouse](https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/warehouse.py): `pipelines/src/criciq_pipelines/warehouse.py`
- [Data validation](https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/validation.py): `pipelines/src/criciq_pipelines/validation.py`
- [Serving export](https://github.com/mehulp007/criciq/blob/main/pipelines/src/criciq_pipelines/export.py): `pipelines/src/criciq_pipelines/export.py`

### Models and research

- [Model scoring](https://github.com/mehulp007/criciq/blob/main/ml/src/criciq_ml/ball_outcome.py): `ml/src/criciq_ml/ball_outcome.py`
- [Analytics Lab](https://github.com/mehulp007/criciq/blob/main/ml/src/criciq_ml/lab.py): `ml/src/criciq_ml/lab.py`

### Serving API

- [FastAPI application](https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/main.py): `backend/src/criciq_api/main.py`
- [API routes](https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/api/v1/router.py): `backend/src/criciq_api/api/v1/router.py`
- [Domain services](https://github.com/mehulp007/criciq/tree/main/backend/src/criciq_api/services): `backend/src/criciq_api/services`
- [Query repositories](https://github.com/mehulp007/criciq/tree/main/backend/src/criciq_api/repositories): `backend/src/criciq_api/repositories`
- [Serving database](https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/db.py): `backend/src/criciq_api/db.py`

### Web experience

- [Next.js pages](https://github.com/mehulp007/criciq/tree/main/frontend/app): `frontend/app`
- [API client](https://github.com/mehulp007/criciq/blob/main/frontend/lib/api/client.ts): `frontend/lib/api/client.ts`
- [Match replay](https://github.com/mehulp007/criciq/blob/main/frontend/lib/replay/engine.ts): `frontend/lib/replay/engine.ts`
- [Simulation routes](https://github.com/mehulp007/criciq/blob/main/frontend/app/api/simulate/match/route.ts): `frontend/app/api/simulate/match/route.ts`

### Simulation

- [Simulation engine](https://github.com/mehulp007/criciq/blob/main/core/src/criciq_core/simulation.py): `core/src/criciq_core/simulation.py`
- [Simulation service](https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/services/simulation.py): `backend/src/criciq_api/services/simulation.py`
- [Simulation queries](https://github.com/mehulp007/criciq/blob/main/backend/src/criciq_api/repositories/simulation.py): `backend/src/criciq_api/repositories/simulation.py`

### Other components

- **Cricket analyst**
- **Cricsheet data**

## Connections

- Cricket analyst → Next.js pages: explores analytics (evidence: `README.md`)
- Cricsheet data → Ball extraction: supplies ball data (evidence: `README.md`)
- Data pipeline → Ball extraction: runs extraction (evidence: `pipelines/src/criciq_pipelines/pipeline.py`)
- Data pipeline → Analytics warehouse: builds warehouse (evidence: `pipelines/src/criciq_pipelines/pipeline.py`)
- Data pipeline → Data validation: validates data (evidence: `pipelines/src/criciq_pipelines/pipeline.py`)
- Data pipeline → Serving export: exports serving data (evidence: `pipelines/src/criciq_pipelines/pipeline.py`)
- Data pipeline → Analytics warehouse: reads and writes (evidence: `pipelines/src/criciq_pipelines/pipeline.py`)
- Analytics warehouse → Model scoring: provides model data (evidence: `README.md`)
- Model scoring → Serving database: publishes predictions (evidence: `README.md`)
- Analytics warehouse → Serving export: exports database (evidence: `pipelines/src/criciq_pipelines/pipeline.py`)
- Serving database → FastAPI application: opens serving data (evidence: `backend/src/criciq_api/main.py`)
- FastAPI application → API routes: mounts routes (evidence: `backend/src/criciq_api/main.py`)
- API routes → Domain services: dispatches requests
- Domain services → Query repositories: queries data (evidence: `backend/src/criciq_api/services/simulation.py`)
- Query repositories → Serving database: reads data
- Next.js pages → API client: requests analytics (evidence: `README.md`)
- API client → FastAPI application: calls API (evidence: `README.md`)
- Next.js pages → Match replay: replays matches (evidence: `README.md`)
- Next.js pages → Simulation routes: offers simulation (evidence: `README.md`)
- Simulation routes → Simulation service: submits simulation
- Simulation service → Simulation queries: loads simulation data (evidence: `backend/src/criciq_api/services/simulation.py`)
- Simulation service → Simulation engine: runs simulation (evidence: `backend/src/criciq_api/services/simulation.py`)
- Analytics Lab → Serving database: analyzes scored data (evidence: `ml/src/criciq_ml/lab.py`)