# kasturimaheshbabu2316-mc/whatsapp-on-cruise-control architecture

> Architecture diagram of the GitHub repository kasturimaheshbabu2316-mc/whatsapp-on-cruise-control, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control
- Repository: https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control

## Overview

This repository is a WhatsApp conversation-personalization toolkit: it prepares conversation examples and persona signals, retrieves relationship-specific examples, and uses them to generate replies. A separate decision engine applies safety rules and classifies whether a message should be answered. The sampled code supports these capabilities, but does not establish an integrated WhatsApp listener or a caller connecting routing, safety decisions, and reply generation. The README is empty; unsampled subsystems are represented only where the tree or documented code supports them.

Main entry points: [`agent/generator.py`](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/agent/generator.py) (Generate reply), [`ingestion/retrieval.py`](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/ingestion/retrieval.py) (Retrieve examples), [`agent/decision_engine.py`](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/agent/decision_engine.py) (Reply-or-ignore decision), [`ingestion/parse_export.py`](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/ingestion/parse_export.py) (Parse reply pairs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Conversation preparation"]
  node_parse["Parse reply pairs<br/>[parse_export.py]"]
  node_pairs["Processed pairs"]
  node_embed["Index conversation pairs<br/>[embed_to_chroma.py]"]
  node_chroma[("Conversation history")]
end

subgraph group_persona["Persona signals"]
  node_persona_source["WhatsApp style history"]
  node_persona_build["Build style signals<br/>[build_persona.py]"]
  node_persona_data["Persona profiles<br/>[persona.json]"]
  node_style_data["Style signals<br/>[style_signals.json]"]
end

subgraph group_runtime["Reply generation"]
  node_router["Resolve relationship<br/>[router.py]"]
  node_relationship_map["Relationship map"]
  node_retrieval["Retrieve examples<br/>[retrieval.py]"]
  node_generator["Generate reply<br/>[generator.py]"]
end

subgraph group_safety["Reply safety"]
  node_decision["Reply-or-ignore decision<br/>[decision_engine.py]"]
  node_decision_log[("Decision log<br/>[decision_log.jsonl]")]
end

node_exports["WhatsApp exports"]
node_gemini{{"Gemini API"}}
node_message(("Incoming message"))

node_exports -->|"reads exports"| node_parse
node_parse -->|"writes pairs"| node_pairs
node_pairs -->|"loads pairs"| node_embed
node_embed -->|"upserts embeddings"| node_chroma
node_persona_source -->|"reads messages"| node_persona_build
node_persona_build -->|"writes signals"| node_style_data
node_relationship_map -->|"maps sender"| node_router
node_message -->|"resolves sender"| node_router
node_message -->|"supplies text"| node_generator
node_generator -->|"requests examples"| node_retrieval
node_retrieval -->|"queries history"| node_chroma
node_retrieval -->|"returns examples"| node_generator
node_generator -->|"loads profile"| node_persona_data
node_generator -->|"requests reply"| node_gemini
node_message -->|"checks message"| node_decision
node_decision -->|"classifies intent"| node_gemini
node_decision -->|"appends decision"| node_decision_log

click node_exports "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/tree/main/data/raw_export"
click node_parse "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/ingestion/parse_export.py"
click node_pairs "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/tree/main/data/processed_pairs"
click node_embed "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/ingestion/embed_to_chroma.py"
click node_persona_source "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/tree/main/data/raw_export"
click node_persona_build "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/persona/build_persona.py"
click node_persona_data "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/persona/persona.json"
click node_style_data "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/persona/style_signals.json"
click node_router "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/router.py"
click node_relationship_map "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/config/relationship_map.json"
click node_retrieval "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/ingestion/retrieval.py"
click node_generator "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/agent/generator.py"
click node_decision "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/agent/decision_engine.py"
click node_decision_log "https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/logs/decision_log.jsonl"

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_parse,node_pairs,node_embed,node_chroma toneBlue
class node_persona_source,node_persona_build,node_persona_data,node_style_data toneAmber
class node_router,node_relationship_map,node_retrieval,node_generator,node_gemini toneMint
class node_decision,node_decision_log toneRose
class node_exports toneTeal
class node_message toneIndigo
```

## Components

### Conversation preparation

- [Parse reply pairs](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/ingestion/parse_export.py): `ingestion/parse_export.py`
- [Processed pairs](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/tree/main/data/processed_pairs): `data/processed_pairs`
- [Index conversation pairs](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/ingestion/embed_to_chroma.py): `ingestion/embed_to_chroma.py`
- **Conversation history**

### Persona signals

- [WhatsApp style history](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/tree/main/data/raw_export): `data/raw_export`
- [Build style signals](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/persona/build_persona.py): `persona/build_persona.py`
- [Persona profiles](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/persona/persona.json): `persona/persona.json`
- [Style signals](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/persona/style_signals.json): `persona/style_signals.json`

### Reply generation

- [Resolve relationship](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/router.py): `router.py`
- [Relationship map](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/config/relationship_map.json): `config/relationship_map.json`
- [Retrieve examples](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/ingestion/retrieval.py): `ingestion/retrieval.py`
- [Generate reply](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/agent/generator.py): `agent/generator.py`

### Reply safety

- [Reply-or-ignore decision](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/agent/decision_engine.py): `agent/decision_engine.py`
- [Decision log](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/blob/main/logs/decision_log.jsonl): `logs/decision_log.jsonl`

### Other components

- [WhatsApp exports](https://github.com/kasturimaheshbabu2316-mc/whatsapp-on-cruise-control/tree/main/data/raw_export): `data/raw_export`
- **Gemini API**
- **Incoming message**

## Connections

- WhatsApp exports → Parse reply pairs: reads exports
- Parse reply pairs → Processed pairs: writes pairs
- Processed pairs → Index conversation pairs: loads pairs
- Index conversation pairs → Conversation history: upserts embeddings
- WhatsApp style history → Build style signals: reads messages
- Build style signals → Style signals: writes signals
- Relationship map → Resolve relationship: maps sender
- Incoming message → Resolve relationship: resolves sender
- Incoming message → Generate reply: supplies text
- Generate reply → Retrieve examples: requests examples
- Retrieve examples → Conversation history: queries history
- Retrieve examples → Generate reply: returns examples
- Generate reply → Persona profiles: loads profile
- Generate reply → Gemini API: requests reply
- Incoming message → Reply-or-ignore decision: checks message
- Reply-or-ignore decision → Gemini API: classifies intent
- Reply-or-ignore decision → Decision log: appends decision