# sithilsemitha/deathbed-ai architecture

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

- Interactive diagram: https://gitdiagram.com/sithilsemitha/deathbed-ai
- Repository: https://github.com/sithilsemitha/deathbed-ai

## Overview

DeathBed is a text-classification API for life decisions. The main workflow accepts a query, validates and cleans it, predicts a category, derives a subcategory and confidence-based override flag, then returns a summary. A separate training workflow builds a TF-IDF classifier from labeled data. The source scripts expect `data/raw` and `models` paths, but the tree places those resources under `ml_service`; those links are therefore unverified. The README describes Naive Bayes, while the server health response names logistic regression.

Main entry points: [`inference_server.py`](https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py) (HTTP server), [`train_from_csv.py`](https://github.com/sithilsemitha/deathbed-ai/blob/main/train_from_csv.py) (Training pipeline), [`ml_service/models/decision_classifier.pkl`](https://github.com/sithilsemitha/deathbed-ai/blob/main/ml_service/models/decision_classifier.pkl) (Classifier artifact), [`ml_service/models/labels.pkl`](https://github.com/sithilsemitha/deathbed-ai/blob/main/ml_service/models/labels.pkl) (Category labels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Classification API"]
  node_server["HTTP server"]
  node_validation["Input validation"]
  node_cleaning["Text cleaning"]
  node_prediction["Category prediction"]
  node_subcategory["Subcategory mapping"]
  node_response["Response assembly"]
  node_health["Health endpoint"]
end

subgraph group_training["Model training"]
  node_trainer["Training pipeline<br/>[train_from_csv.py]"]
end

subgraph group_artifacts["Data and artifacts"]
  node_dataset["Decision dataset"]
  node_model["Classifier artifact"]
  node_labels["Category labels<br/>[labels.pkl]"]
end

node_caller(("API caller"))

node_caller -->|"sends request"| node_server
node_server -->|"routes classify"| node_validation
node_validation -->|"cleans input"| node_cleaning
node_cleaning -->|"predicts category"| node_prediction
node_validation -->|"maps category"| node_subcategory
node_prediction -->|"provides score"| node_response
node_subcategory -->|"provides label"| node_response
node_server -->|"routes health"| node_health
node_caller -->|"checks status"| node_health
node_trainer -.->|"reads data"| node_dataset
node_trainer -.->|"writes model"| node_model
node_trainer -.->|"writes labels"| node_labels
node_server -.->|"loads model"| node_model
node_server -.->|"loads labels"| node_labels

click node_server "https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py"
click node_validation "https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py"
click node_cleaning "https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py"
click node_prediction "https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py"
click node_subcategory "https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py"
click node_response "https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py"
click node_health "https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py"
click node_trainer "https://github.com/sithilsemitha/deathbed-ai/blob/main/train_from_csv.py"
click node_dataset "https://github.com/sithilsemitha/deathbed-ai/blob/main/ml_service/data/raw/life_decisions_dataset.csv"
click node_model "https://github.com/sithilsemitha/deathbed-ai/blob/main/ml_service/models/decision_classifier.pkl"
click node_labels "https://github.com/sithilsemitha/deathbed-ai/blob/main/ml_service/models/labels.pkl"

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_server,node_validation,node_cleaning,node_prediction,node_subcategory,node_response,node_health toneBlue
class node_trainer toneAmber
class node_dataset,node_model,node_labels,node_caller toneMint
```

## Components

### Classification API

- [HTTP server](https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py): `inference_server.py`
- [Input validation](https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py): `inference_server.py`
- [Text cleaning](https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py): `inference_server.py`
- [Category prediction](https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py): `inference_server.py`
- [Subcategory mapping](https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py): `inference_server.py`
- [Response assembly](https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py): `inference_server.py`
- [Health endpoint](https://github.com/sithilsemitha/deathbed-ai/blob/main/inference_server.py): `inference_server.py`

### Model training

- [Training pipeline](https://github.com/sithilsemitha/deathbed-ai/blob/main/train_from_csv.py): `train_from_csv.py`

### Data and artifacts

- [Decision dataset](https://github.com/sithilsemitha/deathbed-ai/blob/main/ml_service/data/raw/life_decisions_dataset.csv): `ml_service/data/raw/life_decisions_dataset.csv`
- [Classifier artifact](https://github.com/sithilsemitha/deathbed-ai/blob/main/ml_service/models/decision_classifier.pkl): `ml_service/models/decision_classifier.pkl`
- [Category labels](https://github.com/sithilsemitha/deathbed-ai/blob/main/ml_service/models/labels.pkl): `ml_service/models/labels.pkl`

### Other components

- **API caller**

## Connections

- API caller → HTTP server: sends request (evidence: `README.md`)
- HTTP server → Input validation: routes classify (evidence: `inference_server.py`)
- Input validation → Text cleaning: cleans input (evidence: `inference_server.py`)
- Text cleaning → Category prediction: predicts category (evidence: `inference_server.py`)
- Input validation → Subcategory mapping: maps category (evidence: `inference_server.py`)
- Category prediction → Response assembly: provides score (evidence: `inference_server.py`)
- Subcategory mapping → Response assembly: provides label (evidence: `inference_server.py`)
- HTTP server → Health endpoint: routes health (evidence: `inference_server.py`)
- API caller → Health endpoint: checks status (evidence: `README.md`)
- Training pipeline → Decision dataset: reads data
- Training pipeline → Classifier artifact: writes model
- Training pipeline → Category labels: writes labels
- HTTP server → Classifier artifact: loads model
- HTTP server → Category labels: loads labels
