# idkhowtocodefr/vera-engine architecture

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

- Interactive diagram: https://gitdiagram.com/idkhowtocodefr/vera-engine
- Repository: https://github.com/idkhowtocodefr/vera-engine

## Overview

Vera Engine accepts category, merchant, customer, and trigger context, then processes available triggers into WhatsApp engagement actions. Its central workflow distills context, composes and validates a message through cloud-model fallbacks and a local model, and returns actions; a separate reply endpoint classifies incoming messages and chooses a response. The graph reflects the sampled API, composer, and model code plus README-documented behavior; unsampled implementation details are represented only where paths and capabilities are supported.

Main entry points: [`scripts/llm.py`](https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/llm.py) (Model Adapters), [`scripts/composer.py`](https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/composer.py) (Fallback Composer), [`app.py`](https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py) (Trigger Processing), [`dataset`](https://github.com/idkhowtocodefr/vera-engine/tree/main/dataset) (Challenge Seed Data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Context"]
  node_context_api["Context Ingestion<br/>[app.py]"]
  node_context_store[("Context State<br/>[app.py]")]
  node_tick_api["Trigger API<br/>[app.py]"]
  node_reply_api["Reply API<br/>[app.py]"]
  node_health_metadata["Health and Metadata<br/>[app.py]"]
end

subgraph group_engagement["Engagement Workflow"]
  node_trigger_processing["Trigger Processing<br/>[app.py]"]
  node_reply_classification["Reply Classification<br/>[app.py]"]
end

subgraph group_composition["Message Composition"]
  node_composer["Context Distiller<br/>[composer.py]"]
  node_prompt_builder["Prompt Builder<br/>[prompts.py]"]
  node_output_validation["Validation and Repair<br/>[composer.py]"]
end

subgraph group_inference["Model Inference"]
  node_model_router["Fallback Composer<br/>[composer.py]"]
  node_llm_adapter["Model Adapters<br/>[llm.py]"]
  node_local_model["Local Qwen Model<br/>[llm.py]"]
end

node_client(("Challenge Client"))
node_nvidia["NVIDIA NIM"]
node_groq["Groq"]
node_gemini["Gemini"]
node_seed_data["Challenge Seed Data"]

node_client -->|"pushes context"| node_context_api
node_context_api -->|"stores payloads"| node_context_store
node_client -->|"submits triggers"| node_tick_api
node_tick_api -->|"reads contexts"| node_context_store
node_tick_api -->|"dispatches"| node_trigger_processing
node_trigger_processing -->|"loads context"| node_context_store
node_trigger_processing -->|"composes message"| node_composer
node_composer -->|"builds local prompt"| node_prompt_builder
node_composer -->|"requests generation"| node_model_router
node_model_router -->|"tries model tiers"| node_llm_adapter
node_llm_adapter -->|"calls first"| node_nvidia
node_llm_adapter -->|"falls back"| node_groq
node_llm_adapter -->|"falls back"| node_gemini
node_llm_adapter -->|"falls back"| node_local_model
node_model_router -->|"validates and repairs"| node_output_validation
node_output_validation -->|"returns result"| node_model_router
node_trigger_processing -->|"returns action"| node_tick_api
node_client -->|"posts reply"| node_reply_api
node_reply_api -->|"classifies message"| node_reply_classification
node_reply_classification -->|"generates response"| node_model_router
node_reply_api -->|"returns decision"| node_client
node_client -->|"requests status"| node_health_metadata
node_seed_data -.->|"supplies test contexts"| node_client

click node_context_api "https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py"
click node_context_store "https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py"
click node_tick_api "https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py"
click node_reply_api "https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py"
click node_health_metadata "https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py"
click node_trigger_processing "https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py"
click node_reply_classification "https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py"
click node_composer "https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/composer.py"
click node_prompt_builder "https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/prompts.py"
click node_output_validation "https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/composer.py"
click node_model_router "https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/composer.py"
click node_llm_adapter "https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/llm.py"
click node_local_model "https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/llm.py"
click node_seed_data "https://github.com/idkhowtocodefr/vera-engine/tree/main/dataset"

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_context_api,node_context_store,node_tick_api,node_reply_api,node_health_metadata,node_client toneBlue
class node_trigger_processing,node_reply_classification toneAmber
class node_composer,node_prompt_builder,node_output_validation toneMint
class node_model_router,node_llm_adapter,node_local_model toneRose
class node_nvidia,node_groq,node_gemini toneIndigo
class node_seed_data toneTeal
```

## Components

### API and Context

- [Context Ingestion](https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py): `app.py`
- [Context State](https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py): `app.py`
- [Trigger API](https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py): `app.py`
- [Reply API](https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py): `app.py`
- [Health and Metadata](https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py): `app.py`

### Engagement Workflow

- [Trigger Processing](https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py): `app.py`
- [Reply Classification](https://github.com/idkhowtocodefr/vera-engine/blob/main/app.py): `app.py`

### Message Composition

- [Context Distiller](https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/composer.py): `scripts/composer.py`
- [Prompt Builder](https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/prompts.py): `scripts/prompts.py`
- [Validation and Repair](https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/composer.py): `scripts/composer.py`

### Model Inference

- [Fallback Composer](https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/composer.py): `scripts/composer.py`
- [Model Adapters](https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/llm.py): `scripts/llm.py`
- [Local Qwen Model](https://github.com/idkhowtocodefr/vera-engine/blob/main/scripts/llm.py): `scripts/llm.py`

### Other components

- **Challenge Client**
- **NVIDIA NIM**
- **Groq**
- **Gemini**
- [Challenge Seed Data](https://github.com/idkhowtocodefr/vera-engine/tree/main/dataset): `dataset`

## Connections

- Challenge Client → Context Ingestion: pushes context
- Context Ingestion → Context State: stores payloads
- Challenge Client → Trigger API: submits triggers
- Trigger API → Context State: reads contexts
- Trigger API → Trigger Processing: dispatches
- Trigger Processing → Context State: loads context
- Trigger Processing → Context Distiller: composes message
- Context Distiller → Prompt Builder: builds local prompt
- Context Distiller → Fallback Composer: requests generation
- Fallback Composer → Model Adapters: tries model tiers
- Model Adapters → NVIDIA NIM: calls first
- Model Adapters → Groq: falls back
- Model Adapters → Gemini: falls back
- Model Adapters → Local Qwen Model: falls back
- Fallback Composer → Validation and Repair: validates and repairs
- Validation and Repair → Fallback Composer: returns result
- Trigger Processing → Trigger API: returns action
- Challenge Client → Reply API: posts reply
- Reply API → Reply Classification: classifies message
- Reply Classification → Fallback Composer: generates response
- Reply API → Challenge Client: returns decision
- Challenge Client → Health and Metadata: requests status
- Challenge Seed Data → Challenge Client: supplies test contexts