# kjudeh/whatsapp-ai-receptionist architecture

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

- Interactive diagram: https://gitdiagram.com/kjudeh/whatsapp-ai-receptionist
- Repository: https://github.com/kjudeh/whatsapp-ai-receptionist

## Overview

This repository is a Railway deployment template for a WhatsApp AI receptionist. A customer message reaches Evolution API, which forwards events to the imported n8n workflow; the workflow filters messages, handles handoff and office-hours behavior, calls an AI provider when appropriate, and sends replies through Evolution. The README documents persistent session and application data in PostgreSQL, Evolution caching in Redis, and instance files on a volume. The workflow JSON and service directories are present, but source excerpts were unavailable, so internal wiring beyond documented relationships is not inferred.

Main entry points: [`services/evolution`](https://github.com/kjudeh/whatsapp-ai-receptionist/tree/main/services/evolution) (Evolution API), [`workflows/whatsapp-ai-receptionist.json`](https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json) (Reception workflow), [`services/n8n`](https://github.com/kjudeh/whatsapp-ai-receptionist/tree/main/services/n8n) (n8n runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_messaging["WhatsApp messaging"]
  node_evolution["Evolution API"]
  node_manager["Instance manager"]
end

subgraph group_workflow["Reception workflow"]
  node_n8n["n8n runtime"]
  node_workflow_json["Reception workflow"]
  node_message_filter["Message filters"]
  node_handoff["Human handoff"]
  node_office_hours["Office-hours reply"]
  node_business_context["Business context"]
end

subgraph group_state["Persistent state"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_volume[("Instance volume")]
end

node_customer(("Customer"))
node_whatsapp(("WhatsApp"))
node_llm["AI provider"]
node_owner(("Business owner"))

node_customer -->|"sends message"| node_whatsapp
node_whatsapp -->|"delivers message"| node_evolution
node_owner -->|"pairs device"| node_manager
node_manager -->|"configures instance"| node_evolution
node_evolution -->|"forwards webhook"| node_n8n
node_n8n -->|"runs"| node_workflow_json
node_workflow_json -->|"filters event"| node_message_filter
node_workflow_json -->|"checks keyword"| node_handoff
node_workflow_json -->|"checks schedule"| node_office_hours
node_workflow_json -->|"provides context"| node_business_context
node_workflow_json -->|"requests answer"| node_llm
node_workflow_json -->|"sends reply"| node_evolution
node_evolution -->|"sends message"| node_whatsapp
node_evolution -->|"stores session data"| node_postgres
node_n8n -->|"stores workflow data"| node_postgres
node_evolution -->|"uses cache"| node_redis
node_evolution -->|"persists instance files"| node_volume

click node_evolution "https://github.com/kjudeh/whatsapp-ai-receptionist/tree/main/services/evolution"
click node_manager "https://github.com/kjudeh/whatsapp-ai-receptionist/tree/main/services/evolution"
click node_n8n "https://github.com/kjudeh/whatsapp-ai-receptionist/tree/main/services/n8n"
click node_workflow_json "https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json"
click node_message_filter "https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json"
click node_handoff "https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json"
click node_office_hours "https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json"
click node_business_context "https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json"

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_evolution,node_manager toneBlue
class node_n8n,node_workflow_json,node_message_filter,node_handoff,node_office_hours,node_business_context toneAmber
class node_postgres,node_redis,node_volume toneMint
class node_customer,node_whatsapp,node_llm,node_owner toneIndigo
```

## Components

### WhatsApp messaging

- [Evolution API](https://github.com/kjudeh/whatsapp-ai-receptionist/tree/main/services/evolution): `services/evolution`
- [Instance manager](https://github.com/kjudeh/whatsapp-ai-receptionist/tree/main/services/evolution): `services/evolution`

### Reception workflow

- [n8n runtime](https://github.com/kjudeh/whatsapp-ai-receptionist/tree/main/services/n8n): `services/n8n`
- [Reception workflow](https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json): `workflows/whatsapp-ai-receptionist.json`
- [Message filters](https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json): `workflows/whatsapp-ai-receptionist.json`
- [Human handoff](https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json): `workflows/whatsapp-ai-receptionist.json`
- [Office-hours reply](https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json): `workflows/whatsapp-ai-receptionist.json`
- [Business context](https://github.com/kjudeh/whatsapp-ai-receptionist/blob/main/workflows/whatsapp-ai-receptionist.json): `workflows/whatsapp-ai-receptionist.json`

### Persistent state

- **PostgreSQL**
- **Redis**
- **Instance volume**

### Other components

- **Customer**
- **WhatsApp**
- **AI provider**
- **Business owner**

## Connections

- Customer → WhatsApp: sends message
- WhatsApp → Evolution API: delivers message
- Business owner → Instance manager: pairs device
- Instance manager → Evolution API: configures instance
- Evolution API → n8n runtime: forwards webhook
- n8n runtime → Reception workflow: runs
- Reception workflow → Message filters: filters event
- Reception workflow → Human handoff: checks keyword
- Reception workflow → Office-hours reply: checks schedule
- Reception workflow → Business context: provides context
- Reception workflow → AI provider: requests answer
- Reception workflow → Evolution API: sends reply
- Evolution API → WhatsApp: sends message
- Evolution API → PostgreSQL: stores session data
- n8n runtime → PostgreSQL: stores workflow data
- Evolution API → Redis: uses cache
- Evolution API → Instance volume: persists instance files