# kamrulhasan12345/sentinel architecture

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

- Interactive diagram: https://gitdiagram.com/kamrulhasan12345/sentinel
- Repository: https://github.com/kamrulhasan12345/sentinel

## Overview

1. **System boundary**
   Sentinel is a self-contained, offline-first mobile app. The runtime architecture is almost entirely on-device: user input, model inference, triage decisioning, medical guidance lookup, and history storage all happen locally. There is no backend service or network API shown in this repository.

2. **App shell and navigation**
   The UI is built with Expo Router in `src/app`. The root layout and drawer layout define the navigation shell, with at least two primary surfaces: the main triage screen (`index.tsx`) and a `library` screen. Supporting routes include a modal, a not-found page, and a web HTML entry. This makes the navigation structure file-based and easy to map as a top-level app shell plus feature screens.

3. **Primary interaction layer**
   `src/screens/ChatScreen.tsx` appears to be the core triage interface. It is the main place where symptoms are entered and results are displayed. The screen is supported by shared UI components in `src/components`, such as themed text, external links, and client-only helpers.

4. **Voice and text input path**
   User input can arrive as typed text or through voice capture. The `useVoiceToText` hook is the dedicated input bridge from microphone speech to text, which is important because the product targets emergency/high-stress usage. That means the app’s first data flow is: microphone or keyboard input → normalized text → triage engine.

5. **Orchestration layer**
   `src/services/HybridEngine.ts` is the central decision-maker. It coordinates the two model paths: the primary CNN classifier and the transformer-based semantic fallback. The readme describes a confidence-based switch, so the architecture should show the hybrid engine choosing the inference path and merging the final intent/severity/confidence result.

6. **Primary ML inference path**
   `CNNEngine.ts` and `CNNVocab.ts` implement the fast, first-pass classification model. The packaged TFLite artifact lives in `src/assets/models/sentinel-cnn-v1/med_intent.tflite`, with a vocabulary file and labels. This is the app’s low-latency intent classifier for common symptom phrases.

7. **Fallback semantic inference path**
   `STEngine.ts` and `STVocab.ts` back the secondary semantic model. The packaged `all-MiniLM-L6-v2` assets include the TFLite transformer and `anchors.json`, which suggests local embedding generation plus similarity matching against precomputed intent anchors. This path resolves unfamiliar phrasing when the CNN confidence is low.

8. **Medical knowledge and response generation**
   `KnowledgeBase.ts` plus `src/data/emergency_data.json` provide the protocol content shown after classification. This is where an inferred intent is turned into first-aid steps, warnings, and escalation guidance. In other words, the models classify the problem, and the knowledge base supplies the human-readable medical response.

9. **Severity, UI mapping, and emergency actions**
   App-wide constants such as `SeverityMap.ts`, `Colors.ts`, `Config.ts`, and `StopWords.ts` shape the final experience. Severity is translated into user-facing UI states and likely determines emergency escalation behavior, including the documented one-tap call to local emergency services for critical cases. The model confidence also feeds visual cues in the UI.

10. **Local persistence and privacy boundary**
   `HistoryService.ts` stores assessment history on-device, which is part of the app’s privacy-first design. This is an important architectural boundary: saved triage sessions stay local instead of being synchronized to a remote account or cloud backend.

11. **ML training pipeline vs runtime app**
   `ml_pipeline/` is a separate build-time environment, not part of the mobile runtime. It contains the training dataset (`data/intents.json`), preprocessing logic, and the notebook used to train the text classifier. The pipeline produces the model artifacts that are later copied into `src/assets/models`, creating a clear separation between offline model development and device inference.

12. **Platform/tooling implications**
   The app is built with React Native, TypeScript, Expo, and TensorFlow Lite. Because native ML is bundled into the client, the project relies on a development build rather than plain Expo Go. The repository also includes standard Expo/EAS configuration and Metro setup, which support packaging the local model assets and native runtime dependencies.

Main entry points: [`src/screens/ChatScreen.tsx`](https://github.com/kamrulhasan12345/sentinel/blob/main/src/screens/ChatScreen.tsx) (Chat screen), [`src/services/HybridEngine.ts`](https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/HybridEngine.ts) (Hybrid engine), [`src/app/_layout.tsx`](https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/_layout.tsx) (App shell), [`src/app/(drawer)/_layout.tsx`](https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/(drawer)/_layout.tsx) (Drawer nav)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_app_shell["App shell<br/>router/layout<br/>[_layout.tsx]"]
  node_drawer_nav["Drawer nav<br/>router/layout<br/>[_layout.tsx]"]
  node_triage_route["Triage route<br/>screen route<br/>[index.tsx]"]
  node_library_route["Library route<br/>screen route<br/>[library.tsx]"]
  node_modal_route["Modal route<br/>[modal.tsx]"]
  node_web_entry["Web entry<br/>[+html.tsx]"]
end

subgraph group_runtime["Runtime"]
  node_chat_screen["Chat screen<br/>triage UI<br/>[ChatScreen.tsx]"]
  node_voice_input(("Voice input<br/>hook<br/>[useVoiceToText.ts]"))
  node_shared_ui["Shared UI<br/>components<br/>[Themed.tsx]"]
  node_hybrid_engine{{"Hybrid engine<br/>decision engine<br/>[HybridEngine.ts]"}}
  node_cnn_engine["CNN engine<br/>classifier<br/>[CNNEngine.ts]"]
  node_st_engine["Semantic engine<br/>embedding matcher<br/>[STEngine.ts]"]
  node_history_service[("History store<br/>local persistence<br/>[HistoryService.ts]")]
  node_cnn_model[("CNN model<br/>tflite asset<br/>[med_intent.tflite]")]
  node_st_model[("Semantic model<br/>tflite asset")]
end

subgraph group_content["Content"]
  node_severity_map["Severity map<br/>constants<br/>[SeverityMap.ts]"]
  node_app_config["Config<br/>constants<br/>[Config.ts]"]
  node_colors_theme["Colors<br/>constants<br/>[Colors.ts]"]
  node_knowledge_base[("Knowledge base<br/>guidance engine<br/>[KnowledgeBase.ts]")]
  node_emergency_data["Emergency data<br/>medical content"]
end

subgraph group_pipeline["ML pipeline"]
  node_ml_preprocess["Preprocess<br/>training script<br/>[preprocess.py]"]
  node_intent_dataset["Intent data<br/>training data<br/>[intents.json]"]
  node_training_notebook["Training notebook"]
end

node_app_shell -->|"hosts"| node_drawer_nav
node_app_shell -->|"routes to"| node_modal_route
node_app_shell -.->|"renders"| node_web_entry
node_drawer_nav -->|"primary screen"| node_triage_route
node_drawer_nav -->|"secondary screen"| node_library_route
node_triage_route -->|"mounts"| node_chat_screen
node_chat_screen -->|"captures speech"| node_voice_input
node_chat_screen -.->|"uses"| node_shared_ui
node_chat_screen -->|"submits text"| node_hybrid_engine
node_chat_screen -->|"records"| node_history_service
node_chat_screen -.->|"maps severity"| node_severity_map
node_chat_screen -.->|"styles"| node_colors_theme
node_chat_screen -.->|"reads settings"| node_app_config
node_hybrid_engine -->|"tries first"| node_cnn_engine
node_hybrid_engine -->|"falls back"| node_st_engine
node_hybrid_engine -->|"requests guidance"| node_knowledge_base
node_hybrid_engine -.->|"emits severity"| node_severity_map
node_cnn_engine -->|"runs"| node_cnn_model
node_st_engine -->|"runs"| node_st_model
node_knowledge_base -->|"loads content"| node_emergency_data
node_knowledge_base -.->|"interprets"| node_severity_map
node_ml_preprocess -->|"prepares"| node_intent_dataset
node_training_notebook -->|"trains with"| node_ml_preprocess
node_training_notebook -.->|"uses"| node_intent_dataset

click node_app_shell "https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/_layout.tsx"
click node_drawer_nav "https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/(drawer)/_layout.tsx"
click node_triage_route "https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/(drawer)/index.tsx"
click node_library_route "https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/(drawer)/library.tsx"
click node_modal_route "https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/modal.tsx"
click node_web_entry "https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/+html.tsx"
click node_chat_screen "https://github.com/kamrulhasan12345/sentinel/blob/main/src/screens/ChatScreen.tsx"
click node_voice_input "https://github.com/kamrulhasan12345/sentinel/blob/main/src/hooks/useVoiceToText.ts"
click node_shared_ui "https://github.com/kamrulhasan12345/sentinel/blob/main/src/components/Themed.tsx"
click node_hybrid_engine "https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/HybridEngine.ts"
click node_cnn_engine "https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/CNNEngine.ts"
click node_st_engine "https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/STEngine.ts"
click node_history_service "https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/HistoryService.ts"
click node_severity_map "https://github.com/kamrulhasan12345/sentinel/blob/main/src/constants/SeverityMap.ts"
click node_app_config "https://github.com/kamrulhasan12345/sentinel/blob/main/src/constants/Config.ts"
click node_colors_theme "https://github.com/kamrulhasan12345/sentinel/blob/main/src/constants/Colors.ts"
click node_knowledge_base "https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/KnowledgeBase.ts"
click node_emergency_data "https://github.com/kamrulhasan12345/sentinel/blob/main/src/data/emergency_data.json"
click node_cnn_model "https://github.com/kamrulhasan12345/sentinel/blob/main/src/assets/models/sentinel-cnn-v1/med_intent.tflite"
click node_st_model "https://github.com/kamrulhasan12345/sentinel/blob/main/src/assets/models/all-MiniLM-L6-v2/sentence_transformer.tflite"
click node_ml_preprocess "https://github.com/kamrulhasan12345/sentinel/blob/main/ml_pipeline/preprocess.py"
click node_intent_dataset "https://github.com/kamrulhasan12345/sentinel/blob/main/ml_pipeline/data/intents.json"
click node_training_notebook "https://github.com/kamrulhasan12345/sentinel/blob/main/ml_pipeline/notebooks/text_classification.ipynb"

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_shell,node_drawer_nav,node_triage_route,node_library_route,node_modal_route,node_web_entry toneBlue
class node_chat_screen,node_voice_input,node_shared_ui,node_hybrid_engine,node_cnn_engine,node_st_engine,node_history_service,node_cnn_model,node_st_model toneAmber
class node_severity_map,node_app_config,node_colors_theme,node_knowledge_base,node_emergency_data toneMint
class node_ml_preprocess,node_intent_dataset,node_training_notebook toneRose
```

## Components

### App shell

Expo Router navigation and screens

- [App shell](https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/_layout.tsx): router/layout · Root Expo Router layout for the mobile app · `src/app/_layout.tsx`
- [Drawer nav](https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/(drawer)/_layout.tsx): router/layout · Primary drawer navigation shell · `src/app/(drawer)/_layout.tsx`
- [Triage route](https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/(drawer)/index.tsx): screen route · Main entry route for the triage experience · `src/app/(drawer)/index.tsx`
- [Library route](https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/(drawer)/library.tsx): screen route · Secondary route for medical reference browsing · `src/app/(drawer)/library.tsx`
- [Modal route](https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/modal.tsx): route · Modal surface for auxiliary flows · `src/app/modal.tsx`
- [Web entry](https://github.com/kamrulhasan12345/sentinel/blob/main/src/app/+html.tsx): web entry · HTML entry used for web rendering · `src/app/+html.tsx`

### Runtime

On-device triage, input, and persistence

- [Chat screen](https://github.com/kamrulhasan12345/sentinel/blob/main/src/screens/ChatScreen.tsx): triage UI · Core symptom intake and result display surface · `src/screens/ChatScreen.tsx`
- [Voice input](https://github.com/kamrulhasan12345/sentinel/blob/main/src/hooks/useVoiceToText.ts): hook · Speech-to-text input bridge · `src/hooks/useVoiceToText.ts`
- [Shared UI](https://github.com/kamrulhasan12345/sentinel/blob/main/src/components/Themed.tsx): components · Themed and reusable presentation components · `src/components/Themed.tsx`
- [Hybrid engine](https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/HybridEngine.ts): decision engine · Routes text through CNN and semantic fallback inference · `src/services/HybridEngine.ts`
- [CNN engine](https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/CNNEngine.ts): classifier · Fast local intent classifier · `src/services/CNNEngine.ts`
- [Semantic engine](https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/STEngine.ts): embedding matcher · Fallback semantic intent resolver · `src/services/STEngine.ts`
- [History store](https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/HistoryService.ts): local persistence · On-device assessment history storage · `src/services/HistoryService.ts`
- [CNN model](https://github.com/kamrulhasan12345/sentinel/blob/main/src/assets/models/sentinel-cnn-v1/med_intent.tflite): tflite asset · Packaged intent classifier artifact · `src/assets/models/sentinel-cnn-v1/med_intent.tflite`
- [Semantic model](https://github.com/kamrulhasan12345/sentinel/blob/main/src/assets/models/all-MiniLM-L6-v2/sentence_transformer.tflite): tflite asset · Packaged transformer embedding artifact · `src/assets/models/all-MiniLM-L6-v2/sentence_transformer.tflite`

### Content

Medical guidance and UI mapping

- [Severity map](https://github.com/kamrulhasan12345/sentinel/blob/main/src/constants/SeverityMap.ts): constants · Maps inferred severity to UI and escalation states · `src/constants/SeverityMap.ts`
- [Config](https://github.com/kamrulhasan12345/sentinel/blob/main/src/constants/Config.ts): constants · App-level behavior and threshold settings · `src/constants/Config.ts`
- [Colors](https://github.com/kamrulhasan12345/sentinel/blob/main/src/constants/Colors.ts): constants · Theme palette used across the UI · `src/constants/Colors.ts`
- [Knowledge base](https://github.com/kamrulhasan12345/sentinel/blob/main/src/services/KnowledgeBase.ts): guidance engine · Turns classified intent into medical guidance · `src/services/KnowledgeBase.ts`
- [Emergency data](https://github.com/kamrulhasan12345/sentinel/blob/main/src/data/emergency_data.json): medical content · First-aid and escalation content bundle · `src/data/emergency_data.json`

### ML pipeline

Offline training and artifact creation

- [Preprocess](https://github.com/kamrulhasan12345/sentinel/blob/main/ml_pipeline/preprocess.py): training script · Dataset preparation and feature engineering for training · `ml_pipeline/preprocess.py`
- [Intent data](https://github.com/kamrulhasan12345/sentinel/blob/main/ml_pipeline/data/intents.json): training data · Labeled intents used to train the classifier · `ml_pipeline/data/intents.json`
- [Training notebook](https://github.com/kamrulhasan12345/sentinel/blob/main/ml_pipeline/notebooks/text_classification.ipynb): training notebook · Notebook used to train and evaluate text classification · `ml_pipeline/notebooks/text_classification.ipynb`

## Connections

- App shell → Drawer nav: hosts · Root app shell mounts the drawer navigator
- App shell → Modal route: routes to · Root layout also exposes modal navigation
- App shell → Web entry: renders · Web HTML entry is part of the app shell
- Drawer nav → Triage route: primary screen · Drawer navigator exposes the main triage surface
- Drawer nav → Library route: secondary screen · Drawer navigator exposes the library surface
- Triage route → Chat screen: mounts · Triage route renders the main chat interface
- Chat screen → Voice input: captures speech · Voice is converted into text for triage input
- Chat screen → Shared UI: uses · Screen is built from shared presentation components
- Chat screen → Hybrid engine: submits text · Normalized symptom text is sent for inference
- Chat screen → History store: records · Assessment sessions are stored locally
- Chat screen → Severity map: maps severity · Severity values drive screen state and escalation cues
- Chat screen → Colors: styles · Theme colors shape the triage UI
- Chat screen → Config: reads settings · UI behavior is influenced by app-level configuration
- Hybrid engine → CNN engine: tries first · Primary path uses the fast CNN classifier
- Hybrid engine → Semantic engine: falls back · Secondary path resolves low-confidence or unfamiliar text
- Hybrid engine → Knowledge base: requests guidance · Engine hands off inferred intent for response generation
- Hybrid engine → Severity map: emits severity · Decision output is normalized to app severity states
- CNN engine → CNN model: runs · CNN engine executes the packaged TFLite model
- Semantic engine → Semantic model: runs · Semantic engine executes the packaged transformer model
- Knowledge base → Emergency data: loads content · Guidance content comes from the local medical data bundle
- Knowledge base → Severity map: interprets · Guidance is aligned with severity categories
- Preprocess → Intent data: prepares · Training pipeline consumes the labeled intent dataset
- Training notebook → Preprocess: trains with · Notebook orchestrates preprocessing and model training
- Training notebook → Intent data: uses · Notebook reads the labeled training set