# castiel0312/kala-tel architecture

> Architecture diagram of the GitHub repository castiel0312/kala-tel, 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/castiel0312/kala-tel
- Repository: https://github.com/castiel0312/kala-tel

## Overview

This repository is a collection of drilling-data tools rather than one unified runtime: NWIS ingests and searches well information, a React component visualizes graph data, lithology scripts train and evaluate models, and kick-detector modules score drilling signals. The clearest user workflows are document upload/search through NWIS and signal scoring through the detector. The README is empty, and several subsystems were not sampled; edges below are limited to indexed references or explicit excerpted calls, so no unverified storage or model-training pipeline is asserted.

Main entry points: [`data/ml/common/force2020_lithology.py`](https://github.com/castiel0312/kala-tel/blob/main/data/ml/common/force2020_lithology.py) (FORCE 2020 Utilities), [`DATA_LAYER/src/api/main.py`](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/api/main.py) (FastAPI Service), [`DATA_LAYER/src/ingestion/pipeline.py`](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/ingestion/pipeline.py) (Ingestion Pipeline), [`DATA_LAYER/graph3d-ui/src/Graph3DView.jsx`](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/Graph3DView.jsx) (3D Graph View)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_nwis["NWIS Data Service"]
  node_api["FastAPI Service<br/>[main.py]"]
  node_config["Settings<br/>[settings.py]"]
  node_ingest["Ingestion Pipeline<br/>[pipeline.py]"]
  node_pdf["PDF Processing<br/>[pdf_processor.py]"]
  node_nlp["NLP Extraction<br/>[nlp_extractor.py]"]
  node_retrieval["Hybrid Retrieval<br/>[hybrid_engine.py]"]
  node_graphapi["Graph API<br/>[graph_viz.py]"]
end

subgraph group_graphui["Graph Visualization"]
  node_view["3D Graph View<br/>[Graph3DView.jsx]"]
  node_stream["Graph Stream Hook<br/>[useGraphStream.js]"]
  node_transform["Graph Transform<br/>[graphTransform.js]"]
  node_styles["Graph Styles<br/>[styles.js]"]
  node_theme["Graph Theme<br/>[theme.js]"]
end

subgraph group_lithology["Lithology Modeling"]
  node_sharedml["FORCE 2020 Utilities"]
  node_gbdt["GBDT Baseline"]
  node_gbdtfeatures["GBDT Feature Set"]
  node_rf["Random Forest"]
  node_cnn["CNN Baseline"]
  node_ablation["Feature Ablation"]
  node_evalgbdt["GBDT Evaluation"]
  node_evalrf["RF Evaluation"]
end

subgraph group_kick["Kick Detection"]
  node_detector["Kick Detector<br/>[detector.py]"]
  node_features["Signal Features<br/>[features.py]"]
  node_columns["Channel Definitions<br/>[columns.py]"]
  node_ensemble["Model Ensemble<br/>[ensemble.py]"]
  node_episodes["Episode Analysis<br/>[episodes.py]"]
end

node_user(("API Client"))
node_browser(("Graph UI User"))
node_mluser(("Model Developer"))
node_driller(("Signal Consumer"))

node_user -->|"uploads or searches"| node_api
node_api -->|"dispatches ingestion"| node_ingest
node_api -->|"dispatches search"| node_retrieval
node_api -->|"routes graph requests"| node_graphapi
node_ingest -->|"uses processor"| node_pdf
node_ingest -->|"uses extractor"| node_nlp
node_api -->|"uses settings"| node_config
node_ingest -->|"uses settings"| node_config
node_retrieval -->|"uses settings"| node_config
node_browser -->|"views graph"| node_view
node_view -->|"reads live graph"| node_stream
node_view -->|"uses styles"| node_styles
node_view -->|"uses colors"| node_theme
node_stream -->|"applies snapshots"| node_transform
node_mluser -->|"trains model"| node_gbdt
node_mluser -->|"trains model"| node_gbdtfeatures
node_mluser -->|"trains model"| node_rf
node_mluser -->|"trains model"| node_cnn
node_mluser -->|"runs ablation"| node_ablation
node_gbdt -->|"uses shared utilities"| node_sharedml
node_gbdtfeatures -->|"uses shared utilities"| node_sharedml
node_rf -->|"uses shared utilities"| node_sharedml
node_ablation -->|"uses shared utilities"| node_sharedml
node_evalgbdt -->|"uses shared utilities"| node_sharedml
node_evalrf -->|"uses shared utilities"| node_sharedml
node_mluser -->|"evaluates model"| node_evalgbdt
node_mluser -->|"evaluates model"| node_evalrf
node_driller -->|"scores signal"| node_detector
node_detector -->|"builds features"| node_features
node_detector -->|"uses ensemble"| node_ensemble
node_detector -->|"uses episodes"| node_episodes
node_features -->|"uses channel definitions"| node_columns

click node_api "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/api/main.py"
click node_config "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/config/settings.py"
click node_ingest "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/ingestion/pipeline.py"
click node_pdf "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/ingestion/pdf_processor.py"
click node_nlp "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/ingestion/nlp_extractor.py"
click node_retrieval "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/retrieval/hybrid_engine.py"
click node_graphapi "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/api/graph_viz.py"
click node_view "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/Graph3DView.jsx"
click node_stream "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/useGraphStream.js"
click node_transform "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/graphTransform.js"
click node_styles "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/styles.js"
click node_theme "https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/theme.js"
click node_sharedml "https://github.com/castiel0312/kala-tel/blob/main/data/ml/common/force2020_lithology.py"
click node_gbdt "https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/training/train_gbdt_baseline.py"
click node_gbdtfeatures "https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/training/train_gbdt_feature_set.py"
click node_rf "https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/training/train_rf_baseline.py"
click node_cnn "https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/training/train_cnn_baseline.py"
click node_ablation "https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/training/train_feature_ablation.py"
click node_evalgbdt "https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/evaluation/evaluate_gbdt_baseline.py"
click node_evalrf "https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/evaluation/evaluate_rf_baseline.py"
click node_detector "https://github.com/castiel0312/kala-tel/blob/main/kick_detector_35f/kickdet/detector.py"
click node_features "https://github.com/castiel0312/kala-tel/blob/main/kick_detector_35f/kickdet/features.py"
click node_columns "https://github.com/castiel0312/kala-tel/blob/main/kick_detector_35f/kickdet/columns.py"
click node_ensemble "https://github.com/castiel0312/kala-tel/blob/main/kick_detector_35f/kickdet/ensemble.py"
click node_episodes "https://github.com/castiel0312/kala-tel/blob/main/kick_detector_35f/kickdet/episodes.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_api,node_config,node_ingest,node_pdf,node_nlp,node_retrieval,node_graphapi,node_user,node_browser toneBlue
class node_view,node_stream,node_transform,node_styles,node_theme toneAmber
class node_sharedml,node_gbdt,node_gbdtfeatures,node_rf,node_cnn,node_ablation,node_evalgbdt,node_evalrf toneMint
class node_detector,node_features,node_columns,node_ensemble,node_episodes toneRose
class node_mluser,node_driller toneIndigo
```

## Components

### NWIS Data Service

- [FastAPI Service](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/api/main.py): `DATA_LAYER/src/api/main.py`
- [Settings](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/config/settings.py): `DATA_LAYER/src/config/settings.py`
- [Ingestion Pipeline](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/ingestion/pipeline.py): `DATA_LAYER/src/ingestion/pipeline.py`
- [PDF Processing](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/ingestion/pdf_processor.py): `DATA_LAYER/src/ingestion/pdf_processor.py`
- [NLP Extraction](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/ingestion/nlp_extractor.py): `DATA_LAYER/src/ingestion/nlp_extractor.py`
- [Hybrid Retrieval](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/retrieval/hybrid_engine.py): `DATA_LAYER/src/retrieval/hybrid_engine.py`
- [Graph API](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/src/api/graph_viz.py): `DATA_LAYER/src/api/graph_viz.py`

### Graph Visualization

- [3D Graph View](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/Graph3DView.jsx): `DATA_LAYER/graph3d-ui/src/Graph3DView.jsx`
- [Graph Stream Hook](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/useGraphStream.js): `DATA_LAYER/graph3d-ui/src/useGraphStream.js`
- [Graph Transform](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/graphTransform.js): `DATA_LAYER/graph3d-ui/src/graphTransform.js`
- [Graph Styles](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/styles.js): `DATA_LAYER/graph3d-ui/src/styles.js`
- [Graph Theme](https://github.com/castiel0312/kala-tel/blob/main/DATA_LAYER/graph3d-ui/src/theme.js): `DATA_LAYER/graph3d-ui/src/theme.js`

### Lithology Modeling

- [FORCE 2020 Utilities](https://github.com/castiel0312/kala-tel/blob/main/data/ml/common/force2020_lithology.py): `data/ml/common/force2020_lithology.py`
- [GBDT Baseline](https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/training/train_gbdt_baseline.py): `data/ml/lithology/training/train_gbdt_baseline.py`
- [GBDT Feature Set](https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/training/train_gbdt_feature_set.py): `data/ml/lithology/training/train_gbdt_feature_set.py`
- [Random Forest](https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/training/train_rf_baseline.py): `data/ml/lithology/training/train_rf_baseline.py`
- [CNN Baseline](https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/training/train_cnn_baseline.py): `data/ml/lithology/training/train_cnn_baseline.py`
- [Feature Ablation](https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/training/train_feature_ablation.py): `data/ml/lithology/training/train_feature_ablation.py`
- [GBDT Evaluation](https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/evaluation/evaluate_gbdt_baseline.py): `data/ml/lithology/evaluation/evaluate_gbdt_baseline.py`
- [RF Evaluation](https://github.com/castiel0312/kala-tel/blob/main/data/ml/lithology/evaluation/evaluate_rf_baseline.py): `data/ml/lithology/evaluation/evaluate_rf_baseline.py`

### Kick Detection

- [Kick Detector](https://github.com/castiel0312/kala-tel/blob/main/kick_detector_35f/kickdet/detector.py): `kick_detector_35f/kickdet/detector.py`
- [Signal Features](https://github.com/castiel0312/kala-tel/blob/main/kick_detector_35f/kickdet/features.py): `kick_detector_35f/kickdet/features.py`
- [Channel Definitions](https://github.com/castiel0312/kala-tel/blob/main/kick_detector_35f/kickdet/columns.py): `kick_detector_35f/kickdet/columns.py`
- [Model Ensemble](https://github.com/castiel0312/kala-tel/blob/main/kick_detector_35f/kickdet/ensemble.py): `kick_detector_35f/kickdet/ensemble.py`
- [Episode Analysis](https://github.com/castiel0312/kala-tel/blob/main/kick_detector_35f/kickdet/episodes.py): `kick_detector_35f/kickdet/episodes.py`

### Other components

- **API Client**
- **Graph UI User**
- **Model Developer**
- **Signal Consumer**

## Connections

- API Client → FastAPI Service: uploads or searches (evidence: `DATA_LAYER/src/api/main.py`)
- FastAPI Service → Ingestion Pipeline: dispatches ingestion (evidence: `DATA_LAYER/src/api/main.py`)
- FastAPI Service → Hybrid Retrieval: dispatches search (evidence: `DATA_LAYER/src/api/main.py`)
- FastAPI Service → Graph API: routes graph requests (evidence: `DATA_LAYER/src/api/main.py`)
- Ingestion Pipeline → PDF Processing: uses processor (evidence: `DATA_LAYER/src/ingestion/pipeline.py`)
- Ingestion Pipeline → NLP Extraction: uses extractor (evidence: `DATA_LAYER/src/ingestion/pipeline.py`)
- FastAPI Service → Settings: uses settings (evidence: `DATA_LAYER/src/api/main.py`)
- Ingestion Pipeline → Settings: uses settings (evidence: `DATA_LAYER/src/ingestion/pipeline.py`)
- Hybrid Retrieval → Settings: uses settings (evidence: `DATA_LAYER/src/retrieval/hybrid_engine.py`)
- Graph UI User → 3D Graph View: views graph
- 3D Graph View → Graph Stream Hook: reads live graph (evidence: `DATA_LAYER/graph3d-ui/src/Graph3DView.jsx`)
- 3D Graph View → Graph Styles: uses styles (evidence: `DATA_LAYER/graph3d-ui/src/Graph3DView.jsx`)
- 3D Graph View → Graph Theme: uses colors (evidence: `DATA_LAYER/graph3d-ui/src/Graph3DView.jsx`)
- Graph Stream Hook → Graph Transform: applies snapshots (evidence: `DATA_LAYER/graph3d-ui/src/useGraphStream.js`)
- Model Developer → GBDT Baseline: trains model
- Model Developer → GBDT Feature Set: trains model
- Model Developer → Random Forest: trains model
- Model Developer → CNN Baseline: trains model
- Model Developer → Feature Ablation: runs ablation
- GBDT Baseline → FORCE 2020 Utilities: uses shared utilities (evidence: `data/ml/lithology/training/train_gbdt_baseline.py`)
- GBDT Feature Set → FORCE 2020 Utilities: uses shared utilities (evidence: `data/ml/lithology/training/train_gbdt_feature_set.py`)
- Random Forest → FORCE 2020 Utilities: uses shared utilities (evidence: `data/ml/lithology/training/train_rf_baseline.py`)
- Feature Ablation → FORCE 2020 Utilities: uses shared utilities (evidence: `data/ml/lithology/training/train_feature_ablation.py`)
- GBDT Evaluation → FORCE 2020 Utilities: uses shared utilities (evidence: `data/ml/lithology/evaluation/evaluate_gbdt_baseline.py`)
- RF Evaluation → FORCE 2020 Utilities: uses shared utilities (evidence: `data/ml/lithology/evaluation/evaluate_rf_baseline.py`)
- Model Developer → GBDT Evaluation: evaluates model
- Model Developer → RF Evaluation: evaluates model
- Signal Consumer → Kick Detector: scores signal
- Kick Detector → Signal Features: builds features (evidence: `kick_detector_35f/kickdet/detector.py`)
- Kick Detector → Model Ensemble: uses ensemble (evidence: `kick_detector_35f/kickdet/detector.py`)
- Kick Detector → Episode Analysis: uses episodes (evidence: `kick_detector_35f/kickdet/detector.py`)
- Signal Features → Channel Definitions: uses channel definitions (evidence: `kick_detector_35f/kickdet/features.py`)
