# usualdork/aiwhisper architecture

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

- Interactive diagram: https://gitdiagram.com/usualdork/aiwhisper
- Repository: https://github.com/usualdork/aiwhisper

## Overview

#### Purpose and Entry Points
AIWhisper is a Next.js WhatsApp automation console for configuring AI agents, connecting a WhatsApp Web account, monitoring inbox activity, and generating Gemini-based replies. The browser application begins at `src/app/page.tsx`, with authenticated/console-style pages grouped under `src/app/(app)/layout.tsx`. HTTP integration boundaries are Next.js route handlers under `src/app/api`.

#### Management Console
The app router serves dashboard, inbox, agents, knowledge-base, activity, and settings views. Feature-level client components encapsulate the operational UI:
- Agent design/listing: `src/app/(app)/agents/page.tsx`, `src/components/agent-designer.tsx`, `src/components/agent-list.tsx`
- Inbox and conversation handling: `src/app/(app)/inbox/page.tsx`, `src/components/inbox-layout.tsx`
- Knowledge and WhatsApp QR UX: `src/app/(app)/knowledge-base/page.tsx`, `src/components/knowledge-base-manager.tsx`, `src/components/qr-login.tsx`

#### API and Application Boundary
Route handlers expose REST-style endpoints consumed by the UI and external callers. They partition the domain into agents, inbox/messages, knowledge ingestion, activity logs, dashboard statistics, and WhatsApp lifecycle:
- `src/app/api/agents/route.ts`, `src/app/api/inbox/messages/[chatId]/route.ts`
- `src/app/api/knowledge/parse/route.ts`, `src/app/api/dashboard/stats/route.ts`
- `src/app/api/whatsapp/init/route.ts`, `src/app/api/whatsapp/send/route.ts`, `src/app/api/whatsapp/status/route.ts`

#### AI Response Pipeline
Genkit hosts the AI runtime and defines an intelligent-response-selection flow, backed by Google Gemini credentials supplied through environment configuration. The intended flow is inbound WhatsApp message/context → response-selection flow → generated reply → WhatsApp send operation.
- `src/ai/genkit.ts`
- `src/ai/flows/intelligent-response-selection.ts`
- `src/lib/ai.ts`

`src/ai/dev.ts` is the separate Genkit development entry point, run alongside Next.js via `genkit:dev`.

#### WhatsApp Integration
Baileys provides the persistent WhatsApp Web/WebSocket connection, QR authentication, outbound messaging, status inspection, and logout. The client adapter isolates this stateful external integration from HTTP endpoints.
- `src/lib/whatsapp-client.ts`
- `src/app/api/whatsapp/init/route.ts`
- `src/app/api/whatsapp/logout/route.ts`

This is a material runtime boundary: the Next.js server/API layer invokes a Node-compatible, connection-owning WhatsApp client rather than directly exposing Baileys to the browser.

#### Persistence and Operational Data
The repository currently contains JSON datasets for agents, conversations, messages, knowledge, logs, and aggregate stats. The database abstraction and server actions are the likely access boundary between routes/UI and persisted state.
- `src/lib/db.ts`, `src/lib/actions.ts`
- `src/data/agents.json`, `src/data/conversations.json`, `src/data/messages.json`
- `src/data/knowledge.json`, `src/data/logs.json`, `src/data/stats.json`

#### Runtime and Dependencies
Primary runtime is Node.js 18+ with Next.js 15 and React. Tailwind/Radix-based UI is rendered by the App Router; Recharts supports analytics views. External services are Google Gemini and WhatsApp Web through Baileys. WhatsApp session state is file-based per the project design, while business/analytics data is represented locally in JSON.

Main entry points: [`src/app/api/agents/route.ts`](https://github.com/usualdork/aiwhisper/blob/main/src/app/api/agents/route.ts) (Domain route handlers), [`src/app/(app)/layout.tsx`](https://github.com/usualdork/aiwhisper/blob/main/src/app/(app)/layout.tsx) (Console layout), [`src/lib/whatsapp-client.ts`](https://github.com/usualdork/aiwhisper/blob/main/src/lib/whatsapp-client.ts) (WhatsApp client adapter), [`src/components/knowledge-base-manager.tsx`](https://github.com/usualdork/aiwhisper/blob/main/src/components/knowledge-base-manager.tsx) (Knowledge and QR UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Management Console"]
  node_entry["App entry<br/>Next.js page<br/>[page.tsx]"]
  node_app_layout["Console layout<br/>App Router layout<br/>[layout.tsx]"]
  node_agent_ui["Agent management<br/>client UI<br/>[agent-designer.tsx]"]
  node_inbox_ui["Inbox workspace<br/>client UI<br/>[inbox-layout.tsx]"]
  node_knowledge_ui["Knowledge and QR UI<br/>client UI"]
end

subgraph group_api["Next.js API"]
  node_routes{{"Domain route handlers<br/>REST API<br/>[route.ts]"}}
  node_whatsapp_routes{{"WhatsApp route handlers<br/>REST API<br/>[route.ts]"}}
end

subgraph group_ai["AI Runtime"]
  node_ai_adapter["AI service adapter<br/>AI boundary<br/>[ai.ts]"]
  node_response_flow["Response selection flow<br/>Genkit flow"]
  node_genkit{{"Genkit runtime<br/>AI runtime<br/>[genkit.ts]"}}
  node_genkit_dev["Genkit dev entry<br/>development runtime<br/>[dev.ts]"]
  node_gemini(("Google Gemini<br/>external AI service"))
end

subgraph group_whatsapp["WhatsApp Integration"]
  node_whatsapp_client["WhatsApp client adapter<br/>Baileys connection owner<br/>[whatsapp-client.ts]"]
  node_whatsapp_web(("WhatsApp Web<br/>external messaging service"))
  node_session_state[("WhatsApp session files<br/>file-based session state")]
end

subgraph group_data["Persistence"]
  node_db["Data access boundary<br/>database abstraction<br/>[db.ts]"]
  node_actions["Server actions<br/>application actions<br/>[actions.ts]"]
  node_json_data[("Operational JSON data<br/>local datasets<br/>[agents.json]")]
end

node_entry -->|"enters console"| node_app_layout
node_app_layout -->|"renders"| node_agent_ui
node_app_layout -->|"renders"| node_inbox_ui
node_app_layout -->|"renders"| node_knowledge_ui
node_agent_ui -->|"manages agents"| node_routes
node_inbox_ui -->|"loads conversations"| node_routes
node_knowledge_ui -->|"ingests knowledge"| node_routes
node_knowledge_ui -->|"starts QR login"| node_whatsapp_routes
node_routes -->|"invokes"| node_actions
node_actions -->|"uses"| node_db
node_db -->|"reads and writes"| node_json_data
node_routes -->|"requests reply generation"| node_ai_adapter
node_ai_adapter -->|"invokes"| node_response_flow
node_response_flow -->|"runs on"| node_genkit
node_genkit -->|"uses"| node_gemini
node_genkit_dev -.->|"loads flows"| node_genkit
node_routes -->|"dispatches generated reply"| node_whatsapp_routes
node_whatsapp_routes -->|"controls"| node_whatsapp_client
node_whatsapp_client -->|"WebSocket connection"| node_whatsapp_web
node_whatsapp_client -->|"persists auth"| node_session_state
node_whatsapp_client -->|"inbound message context"| node_routes

click node_entry "https://github.com/usualdork/aiwhisper/blob/main/src/app/page.tsx"
click node_app_layout "https://github.com/usualdork/aiwhisper/blob/main/src/app/(app)/layout.tsx"
click node_agent_ui "https://github.com/usualdork/aiwhisper/blob/main/src/components/agent-designer.tsx"
click node_inbox_ui "https://github.com/usualdork/aiwhisper/blob/main/src/components/inbox-layout.tsx"
click node_knowledge_ui "https://github.com/usualdork/aiwhisper/blob/main/src/components/knowledge-base-manager.tsx"
click node_routes "https://github.com/usualdork/aiwhisper/blob/main/src/app/api/agents/route.ts"
click node_whatsapp_routes "https://github.com/usualdork/aiwhisper/blob/main/src/app/api/whatsapp/init/route.ts"
click node_db "https://github.com/usualdork/aiwhisper/blob/main/src/lib/db.ts"
click node_actions "https://github.com/usualdork/aiwhisper/blob/main/src/lib/actions.ts"
click node_json_data "https://github.com/usualdork/aiwhisper/blob/main/src/data/agents.json"
click node_ai_adapter "https://github.com/usualdork/aiwhisper/blob/main/src/lib/ai.ts"
click node_response_flow "https://github.com/usualdork/aiwhisper/blob/main/src/ai/flows/intelligent-response-selection.ts"
click node_genkit "https://github.com/usualdork/aiwhisper/blob/main/src/ai/genkit.ts"
click node_genkit_dev "https://github.com/usualdork/aiwhisper/blob/main/src/ai/dev.ts"
click node_whatsapp_client "https://github.com/usualdork/aiwhisper/blob/main/src/lib/whatsapp-client.ts"

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_entry,node_app_layout,node_agent_ui,node_inbox_ui,node_knowledge_ui toneBlue
class node_routes,node_whatsapp_routes toneAmber
class node_ai_adapter,node_response_flow,node_genkit,node_genkit_dev,node_gemini toneMint
class node_whatsapp_client,node_whatsapp_web,node_session_state toneRose
class node_db,node_actions,node_json_data toneIndigo
```

## Components

### Management Console

- [App entry](https://github.com/usualdork/aiwhisper/blob/main/src/app/page.tsx): Next.js page · Browser application entry point. · `src/app/page.tsx`
- [Console layout](https://github.com/usualdork/aiwhisper/blob/main/src/app/(app)/layout.tsx): App Router layout · Shared authenticated console shell. · `src/app/(app)/layout.tsx`
- [Agent management](https://github.com/usualdork/aiwhisper/blob/main/src/components/agent-designer.tsx): client UI · Agent listing and design interface. · `src/components/agent-designer.tsx`
- [Inbox workspace](https://github.com/usualdork/aiwhisper/blob/main/src/components/inbox-layout.tsx): client UI · Conversation monitoring and handling UI. · `src/components/inbox-layout.tsx`
- [Knowledge and QR UI](https://github.com/usualdork/aiwhisper/blob/main/src/components/knowledge-base-manager.tsx): client UI · Knowledge management and WhatsApp login UX. · `src/components/knowledge-base-manager.tsx`

### Next.js API

- [Domain route handlers](https://github.com/usualdork/aiwhisper/blob/main/src/app/api/agents/route.ts): REST API · Agents, inbox, knowledge, activity, and dashboard endpoints. · `src/app/api/agents/route.ts`
- [WhatsApp route handlers](https://github.com/usualdork/aiwhisper/blob/main/src/app/api/whatsapp/init/route.ts): REST API · Lifecycle, status, and send endpoints. · `src/app/api/whatsapp/init/route.ts`

### AI Runtime

- [AI service adapter](https://github.com/usualdork/aiwhisper/blob/main/src/lib/ai.ts): AI boundary · Application-facing Gemini response generation interface. · `src/lib/ai.ts`
- [Response selection flow](https://github.com/usualdork/aiwhisper/blob/main/src/ai/flows/intelligent-response-selection.ts): Genkit flow · Selects and generates an intelligent reply from inbound context. · `src/ai/flows/intelligent-response-selection.ts`
- [Genkit runtime](https://github.com/usualdork/aiwhisper/blob/main/src/ai/genkit.ts): AI runtime · Hosts flows with Google Gemini credentials. · `src/ai/genkit.ts`
- [Genkit dev entry](https://github.com/usualdork/aiwhisper/blob/main/src/ai/dev.ts): development runtime · Separate local Genkit process. · `src/ai/dev.ts`
- **Google Gemini**: external AI service

### WhatsApp Integration

- [WhatsApp client adapter](https://github.com/usualdork/aiwhisper/blob/main/src/lib/whatsapp-client.ts): Baileys connection owner · Owns persistent WhatsApp Web state, QR auth, and messaging. · `src/lib/whatsapp-client.ts`
- **WhatsApp Web**: external messaging service
- **WhatsApp session files**: file-based session state

### Persistence

- [Data access boundary](https://github.com/usualdork/aiwhisper/blob/main/src/lib/db.ts): database abstraction · Server-side access to operational datasets. · `src/lib/db.ts`
- [Server actions](https://github.com/usualdork/aiwhisper/blob/main/src/lib/actions.ts): application actions · `src/lib/actions.ts`
- [Operational JSON data](https://github.com/usualdork/aiwhisper/blob/main/src/data/agents.json): local datasets · Agents, conversations, messages, knowledge, logs, and statistics. · `src/data/agents.json`

## Connections

- App entry → Console layout: enters console
- Console layout → Agent management: renders
- Console layout → Inbox workspace: renders
- Console layout → Knowledge and QR UI: renders
- Agent management → Domain route handlers: manages agents
- Inbox workspace → Domain route handlers: loads conversations
- Knowledge and QR UI → Domain route handlers: ingests knowledge
- Knowledge and QR UI → WhatsApp route handlers: starts QR login
- Domain route handlers → Server actions: invokes
- Server actions → Data access boundary: uses
- Data access boundary → Operational JSON data: reads and writes
- Domain route handlers → AI service adapter: requests reply generation
- AI service adapter → Response selection flow: invokes
- Response selection flow → Genkit runtime: runs on
- Genkit runtime → Google Gemini: uses
- Genkit dev entry → Genkit runtime: loads flows
- Domain route handlers → WhatsApp route handlers: dispatches generated reply
- WhatsApp route handlers → WhatsApp client adapter: controls
- WhatsApp client adapter → WhatsApp Web: WebSocket connection
- WhatsApp client adapter → WhatsApp session files: persists auth
- WhatsApp client adapter → Domain route handlers: inbound message context