# niyatiswaroop/magicpin-vera-ai architecture

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

- Interactive diagram: https://gitdiagram.com/niyatiswaroop/magicpin-vera-ai
- Repository: https://github.com/niyatiswaroop/magicpin-vera-ai

## Overview

Vera is a deterministic outreach bot for the magicpin AI challenge. Its main workflow accepts versioned category, merchant, trigger, and customer contexts; resolves a trigger bundle on a periodic tick; composes and validates a personalized message; then records conversation and suppression state before returning an action. Merchant/customer replies follow a separate rule-based multi-turn path for intent detection, answers, and graceful exits. The graph also preserves category voice, trigger-kind specifications, and the optional local Ollama phrasing layer. Relationships reflect the README and shown imports/calls; unsampled implementation details are not inferred.

Main entry points: [`bot.py`](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/bot.py) (HTTP Endpoints), [`composer.py`](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/composer.py) (Message Composer), [`conversation_handlers.py`](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/conversation_handlers.py) (Reply Handler), [`llm.py`](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/llm.py) (Local Model Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Bot API"]
  node_bot["HTTP Endpoints<br/>[bot.py]"]
end

subgraph group_state["Context State"]
  node_context[("Versioned Contexts<br/>[store.py]")]
  node_conversations[("Conversation State<br/>[store.py]")]
end

subgraph group_composition["Message Composition"]
  node_composer["Message Composer<br/>[composer.py]"]
  node_facts["Provenance and Rules<br/>[facts.py]"]
  node_kinds["Trigger Specifications<br/>[kinds.py]"]
  node_voice["Category Voice<br/>[voice.py]"]
end

subgraph group_engagement["Reply Handling"]
  node_handler["Reply Handler"]
end

subgraph group_optional["Optional Model"]
  node_llm["Local Model Client<br/>[llm.py]"]
end

node_client(("Challenge Harness"))
node_ollama["Ollama Service"]

node_client -->|"pushes contexts"| node_bot
node_client -->|"requests tick"| node_bot
node_client -->|"sends reply"| node_bot
node_bot -->|"stores and resolves"| node_context
node_bot -->|"composes action"| node_composer
node_bot -->|"routes reply"| node_handler
node_bot -->|"records turns"| node_conversations
node_composer -->|"extracts and validates"| node_facts
node_composer -->|"selects specification"| node_kinds
node_composer -->|"builds voice plan"| node_voice
node_composer -->|"phrases optionally"| node_llm
node_llm -->|"requests completion"| node_ollama
node_handler -.->|"tracks inbound state"| node_conversations
node_bot -->|"returns actions"| node_client

click node_bot "https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/bot.py"
click node_context "https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/store.py"
click node_conversations "https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/store.py"
click node_composer "https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/composer.py"
click node_facts "https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/facts.py"
click node_kinds "https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/kinds.py"
click node_voice "https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/voice.py"
click node_handler "https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/conversation_handlers.py"
click node_llm "https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/llm.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_bot toneBlue
class node_context,node_conversations toneAmber
class node_composer,node_facts,node_kinds,node_voice toneMint
class node_handler toneRose
class node_llm,node_client,node_ollama toneIndigo
```

## Components

### Bot API

- [HTTP Endpoints](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/bot.py): `bot.py`

### Context State

- [Versioned Contexts](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/store.py): `store.py`
- [Conversation State](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/store.py): `store.py`

### Message Composition

- [Message Composer](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/composer.py): `composer.py`
- [Provenance and Rules](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/facts.py): `facts.py`
- [Trigger Specifications](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/kinds.py): `kinds.py`
- [Category Voice](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/voice.py): `voice.py`

### Reply Handling

- [Reply Handler](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/conversation_handlers.py): `conversation_handlers.py`

### Optional Model

- [Local Model Client](https://github.com/niyatiswaroop/magicpin-vera-ai/blob/main/llm.py): `llm.py`

### Other components

- **Challenge Harness**
- **Ollama Service**

## Connections

- Challenge Harness → HTTP Endpoints: pushes contexts (evidence: `README.md`)
- Challenge Harness → HTTP Endpoints: requests tick (evidence: `README.md`)
- Challenge Harness → HTTP Endpoints: sends reply (evidence: `README.md`)
- HTTP Endpoints → Versioned Contexts: stores and resolves (evidence: `bot.py`)
- HTTP Endpoints → Message Composer: composes action (evidence: `bot.py`)
- HTTP Endpoints → Reply Handler: routes reply (evidence: `README.md`)
- HTTP Endpoints → Conversation State: records turns (evidence: `bot.py`)
- Message Composer → Provenance and Rules: extracts and validates (evidence: `composer.py`)
- Message Composer → Trigger Specifications: selects specification (evidence: `composer.py`)
- Message Composer → Category Voice: builds voice plan (evidence: `composer.py`)
- Message Composer → Local Model Client: phrases optionally (evidence: `README.md`)
- Local Model Client → Ollama Service: requests completion (evidence: `llm.py`)
- Reply Handler → Conversation State: tracks inbound state
- HTTP Endpoints → Challenge Harness: returns actions (evidence: `bot.py`)