# bellputrii/api-drilling-activity architecture

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

- Interactive diagram: https://gitdiagram.com/bellputrii/api-drilling-activity
- Repository: https://github.com/bellputrii/api-drilling-activity

## Overview

Activity Classifier API serves drilling-activity and casing-trip predictions, either from submitted batches or fetched well data; a realtime scheduler also fetches, predicts, and records results periodically. The prediction service uses ONNX models loaded by the core layer, while route and scheduler components persist predictions. The README describes history and model/health endpoints, but the sampled route excerpts do not show those handlers. The README says MySQL; the inspected connection code configures SQLite. Edges reflect shown calls or documented behavior; unsampled subsystem internals are not inferred.

Main entry points: [`database/connection.py`](https://github.com/bellputrii/api-drilling-activity/blob/dev/database/connection.py) (Database sessions), [`routes/predict_api.py`](https://github.com/bellputrii/api-drilling-activity/blob/dev/routes/predict_api.py) (Well prediction routes), [`scheduler/realtime_scheduler.py`](https://github.com/bellputrii/api-drilling-activity/blob/dev/scheduler/realtime_scheduler.py) (Realtime schedulers), [`services/prediction_service.py`](https://github.com/bellputrii/api-drilling-activity/blob/dev/services/prediction_service.py) (Prediction service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and orchestration"]
  node_app["FastAPI application<br/>[app.py]"]
  node_activity_routes["Activity routes<br/>[activity_route.py]"]
  node_prediction_routes["Well prediction routes<br/>[predict_api.py]"]
  node_realtime_jobs["Realtime schedulers"]
  node_drilling_job["Drilling batch job"]
  node_casing_job["Casing batch job"]
  node_request_schemas["Prediction schemas<br/>[activity_schema.py]"]
end

subgraph group_ingest["Well data ingestion"]
  node_well_fetch["Well data fetcher<br/>[fetch_api.py]"]
  node_field_mapping["Well field maps<br/>[mapping.py]"]
end

subgraph group_inference["Prediction runtime"]
  node_prediction_service["Prediction service"]
  node_model_loader["ONNX model loader<br/>[loader.py]"]
  node_model_config["Model configuration<br/>[config.py]"]
end

subgraph group_persistence["Prediction history"]
  node_db_connection["Database sessions<br/>[connection.py]"]
  node_prediction_records["Prediction records<br/>[models.py]"]
  node_activity_store[("SQLite activity store<br/>[activity.db]")]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"registers routes"| node_activity_routes
node_app -->|"registers routes"| node_prediction_routes
node_app -->|"starts schedulers"| node_realtime_jobs
node_activity_routes -->|"validates input"| node_request_schemas
node_activity_routes -->|"requests predictions"| node_prediction_service
node_activity_routes -->|"gets session"| node_db_connection
node_activity_routes -->|"creates records"| node_prediction_records
node_prediction_routes -->|"fetches well data"| node_well_fetch
node_prediction_routes -->|"maps fields"| node_field_mapping
node_prediction_routes -->|"requests predictions"| node_prediction_service
node_prediction_routes -->|"gets session"| node_db_connection
node_prediction_routes -->|"creates records"| node_prediction_records
node_realtime_jobs -->|"fetches well data"| node_well_fetch
node_realtime_jobs -->|"maps fields"| node_field_mapping
node_realtime_jobs -->|"requests predictions"| node_prediction_service
node_realtime_jobs -->|"opens sessions"| node_db_connection
node_realtime_jobs -->|"creates records"| node_prediction_records
node_drilling_job -->|"requests predictions"| node_prediction_service
node_drilling_job -->|"opens sessions"| node_db_connection
node_drilling_job -->|"creates records"| node_prediction_records
node_casing_job -->|"requests predictions"| node_prediction_service
node_casing_job -->|"opens sessions"| node_db_connection
node_casing_job -->|"creates records"| node_prediction_records
node_prediction_service -->|"uses loaded models"| node_model_loader
node_model_loader -->|"loads paths"| node_model_config
node_db_connection -->|"connects to"| node_activity_store
node_prediction_records -->|"uses base"| node_db_connection

click node_app "https://github.com/bellputrii/api-drilling-activity/blob/dev/app.py"
click node_activity_routes "https://github.com/bellputrii/api-drilling-activity/blob/dev/routes/activity_route.py"
click node_prediction_routes "https://github.com/bellputrii/api-drilling-activity/blob/dev/routes/predict_api.py"
click node_realtime_jobs "https://github.com/bellputrii/api-drilling-activity/blob/dev/scheduler/realtime_scheduler.py"
click node_drilling_job "https://github.com/bellputrii/api-drilling-activity/blob/dev/scheduler/drilling_scheduler.py"
click node_casing_job "https://github.com/bellputrii/api-drilling-activity/blob/dev/scheduler/casing_scheduler.py"
click node_well_fetch "https://github.com/bellputrii/api-drilling-activity/blob/dev/well_client/fetch_api.py"
click node_field_mapping "https://github.com/bellputrii/api-drilling-activity/blob/dev/well_client/mapping.py"
click node_prediction_service "https://github.com/bellputrii/api-drilling-activity/blob/dev/services/prediction_service.py"
click node_model_loader "https://github.com/bellputrii/api-drilling-activity/blob/dev/core/loader.py"
click node_model_config "https://github.com/bellputrii/api-drilling-activity/blob/dev/core/config.py"
click node_request_schemas "https://github.com/bellputrii/api-drilling-activity/blob/dev/schemas/activity_schema.py"
click node_db_connection "https://github.com/bellputrii/api-drilling-activity/blob/dev/database/connection.py"
click node_prediction_records "https://github.com/bellputrii/api-drilling-activity/blob/dev/database/models.py"
click node_activity_store "https://github.com/bellputrii/api-drilling-activity/blob/dev/activity.db"

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_activity_routes,node_prediction_routes,node_realtime_jobs,node_drilling_job,node_casing_job,node_request_schemas,node_client toneBlue
class node_well_fetch,node_field_mapping toneAmber
class node_prediction_service,node_model_loader,node_model_config toneMint
class node_db_connection,node_prediction_records,node_activity_store toneRose
```

## Components

### API and orchestration

- [FastAPI application](https://github.com/bellputrii/api-drilling-activity/blob/dev/app.py): `app.py`
- [Activity routes](https://github.com/bellputrii/api-drilling-activity/blob/dev/routes/activity_route.py): `routes/activity_route.py`
- [Well prediction routes](https://github.com/bellputrii/api-drilling-activity/blob/dev/routes/predict_api.py): `routes/predict_api.py`
- [Realtime schedulers](https://github.com/bellputrii/api-drilling-activity/blob/dev/scheduler/realtime_scheduler.py): `scheduler/realtime_scheduler.py`
- [Drilling batch job](https://github.com/bellputrii/api-drilling-activity/blob/dev/scheduler/drilling_scheduler.py): `scheduler/drilling_scheduler.py`
- [Casing batch job](https://github.com/bellputrii/api-drilling-activity/blob/dev/scheduler/casing_scheduler.py): `scheduler/casing_scheduler.py`
- [Prediction schemas](https://github.com/bellputrii/api-drilling-activity/blob/dev/schemas/activity_schema.py): `schemas/activity_schema.py`

### Well data ingestion

- [Well data fetcher](https://github.com/bellputrii/api-drilling-activity/blob/dev/well_client/fetch_api.py): `well_client/fetch_api.py`
- [Well field maps](https://github.com/bellputrii/api-drilling-activity/blob/dev/well_client/mapping.py): `well_client/mapping.py`

### Prediction runtime

- [Prediction service](https://github.com/bellputrii/api-drilling-activity/blob/dev/services/prediction_service.py): `services/prediction_service.py`
- [ONNX model loader](https://github.com/bellputrii/api-drilling-activity/blob/dev/core/loader.py): `core/loader.py`
- [Model configuration](https://github.com/bellputrii/api-drilling-activity/blob/dev/core/config.py): `core/config.py`

### Prediction history

- [Database sessions](https://github.com/bellputrii/api-drilling-activity/blob/dev/database/connection.py): `database/connection.py`
- [Prediction records](https://github.com/bellputrii/api-drilling-activity/blob/dev/database/models.py): `database/models.py`
- [SQLite activity store](https://github.com/bellputrii/api-drilling-activity/blob/dev/activity.db): `activity.db`

### Other components

- **API client**

## Connections

- API client → FastAPI application: sends requests (evidence: `readme.md`)
- FastAPI application → Activity routes: registers routes (evidence: `app.py`)
- FastAPI application → Well prediction routes: registers routes (evidence: `app.py`)
- FastAPI application → Realtime schedulers: starts schedulers (evidence: `app.py`)
- Activity routes → Prediction schemas: validates input (evidence: `routes/activity_route.py`)
- Activity routes → Prediction service: requests predictions (evidence: `routes/activity_route.py`)
- Activity routes → Database sessions: gets session (evidence: `routes/activity_route.py`)
- Activity routes → Prediction records: creates records (evidence: `routes/activity_route.py`)
- Well prediction routes → Well data fetcher: fetches well data (evidence: `routes/predict_api.py`)
- Well prediction routes → Well field maps: maps fields (evidence: `routes/predict_api.py`)
- Well prediction routes → Prediction service: requests predictions (evidence: `routes/predict_api.py`)
- Well prediction routes → Database sessions: gets session (evidence: `routes/predict_api.py`)
- Well prediction routes → Prediction records: creates records (evidence: `routes/predict_api.py`)
- Realtime schedulers → Well data fetcher: fetches well data (evidence: `scheduler/realtime_scheduler.py`)
- Realtime schedulers → Well field maps: maps fields (evidence: `scheduler/realtime_scheduler.py`)
- Realtime schedulers → Prediction service: requests predictions (evidence: `scheduler/realtime_scheduler.py`)
- Realtime schedulers → Database sessions: opens sessions (evidence: `scheduler/realtime_scheduler.py`)
- Realtime schedulers → Prediction records: creates records (evidence: `scheduler/realtime_scheduler.py`)
- Drilling batch job → Prediction service: requests predictions (evidence: `scheduler/drilling_scheduler.py`)
- Drilling batch job → Database sessions: opens sessions (evidence: `scheduler/drilling_scheduler.py`)
- Drilling batch job → Prediction records: creates records (evidence: `scheduler/drilling_scheduler.py`)
- Casing batch job → Prediction service: requests predictions (evidence: `scheduler/casing_scheduler.py`)
- Casing batch job → Database sessions: opens sessions (evidence: `scheduler/casing_scheduler.py`)
- Casing batch job → Prediction records: creates records (evidence: `scheduler/casing_scheduler.py`)
- Prediction service → ONNX model loader: uses loaded models (evidence: `services/prediction_service.py`)
- ONNX model loader → Model configuration: loads paths (evidence: `core/loader.py`)
- Database sessions → SQLite activity store: connects to (evidence: `database/connection.py`)
- Prediction records → Database sessions: uses base (evidence: `database/models.py`)
