# timifaloye/bookly-support-agent architecture

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

- Interactive diagram: https://gitdiagram.com/timifaloye/bookly-support-agent
- Repository: https://github.com/timifaloye/bookly-support-agent

## Overview

#### Purpose and Entry Points
Bookly Support Agent is a Node.js/TypeScript prototype for SMS/iMessage bookstore support. It accepts customer messages, maintains conversation context, uses LLMs to classify and answer requests, invokes order/return tools, and performs an asynchronous response-accuracy check.

Local CLI execution starts from `src/index.ts`. The production messaging path is the OSIS webhook server in `src/server.ts`, which delegates inbound events to `src/osis/webhookHandler.ts`.

#### OSIS Ingress and Webhook Safety
The OSIS adapter validates, parses, logs, and deduplicates inbound provider webhooks before agent processing:
- `src/osis/webhookHandler.ts`
- `src/osis/signature.ts`
- `src/osis/webhookPayload.ts`

Duplicate protection is backed by SQLite through `src/osis/sqliteDedupeTracker.ts`; this preserves idempotency across development-server restarts. The OSIS client in `src/osis/client.ts` is the outbound messaging boundary and requires OSIS credentials.

#### Conversation Persistence
Conversation history is abstracted behind a store and persisted in SQLite for the webhook runtime:
- `src/state/conversationStore.ts`
- `src/state/sqliteConversationStore.ts`

The agent retrieves prior turns for each customer/channel conversation, appends the inbound message and generated response, and supplies history to the model pipeline. This separates stateful conversations from stateless business tools.

#### Agent Orchestration and LLM Pipeline
`src/claude/agent.ts` is the central coordinator. It runs a three-stage flow:
1. classify user intent;
2. generate a tool-aware support reply;
3. run a background hallucination/accuracy check.

Core model-facing modules are:
- `src/claude/intentClassifier.ts`
- `src/claude/systemPrompt.ts`
- `src/claude/hallucinationCheck.ts`

Anthropic is the primary Claude integration; OpenAI is also required by the application, likely for the accuracy-check stage. Tool execution is mediated rather than directly exposed to model logic via `src/claude/tools.ts` and `src/claude/toolExecutor.ts`.

#### Intent, Tool, and Policy Boundary
Customer requests are mapped to a constrained support domain: verification, order status, return eligibility, and return creation:
- `src/tools/verifyCustomer.ts`
- `src/tools/getOrderStatus.ts`
- `src/tools/checkReturnEligibility.ts`
- `src/tools/createReturnRequest.ts`

Return decision logic is separated from tool transport in `src/tools/returnEligibility.ts`. The tools read/update prototype business records and policies through:
- `src/data/orders.ts`
- `src/data/policy.ts`
- `src/data/returnRequests.ts`

This boundary keeps LLM output from directly mutating data; return creation is an explicit tool action.

#### Return Confirmation and Email
After creating a return request, confirmation content and delivery are handled outside the core agent:
- `src/claude/returnConfirmationMessage.ts`
- `src/lib/confirmation.ts`
- `src/lib/email.ts`

`src/lib/resendEmailClient.ts` integrates Resend when `RESEND_API_KEY` is configured; otherwise confirmations are recorded without actual delivery. This makes email an optional external side effect rather than a prerequisite for request creation.

#### Runtime and Operational Constraints
The runtime is Node.js 24+ with TypeScript. Required external services are Anthropic, OpenAI, and, for live messaging, OSIS; Resend is optional. SQLite supports both conversation persistence and webhook deduplication. `src/lib/devWatchWarning.ts` reflects an operational distinction: auto-restart development mode is not intended for real webhook traffic despite durable local SQLite state.

Main entry points: [`src/claude/agent.ts`](https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/agent.ts) (Support Agent), [`src/osis/webhookHandler.ts`](https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/webhookHandler.ts) (Webhook Handler), [`src/claude/tools.ts`](https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/tools.ts) (Support Toolset), [`src/claude/intentClassifier.ts`](https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/intentClassifier.ts) (Intent Classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["OSIS Messaging"]
  node_server["Webhook Server<br/>entrypoint<br/>[server.ts]"]
  node_webhook["Webhook Handler<br/>OSIS adapter<br/>[webhookHandler.ts]"]
  node_signature["Signature Validation<br/>webhook security<br/>[signature.ts]"]
  node_payload["Webhook Payload Parser<br/>webhook parser<br/>[webhookPayload.ts]"]
  node_dedupe[("Webhook Dedupe<br/>SQLite tracker")]
  node_osis["OSIS Client<br/>messaging client<br/>[client.ts]"]
end

subgraph group_agent["Agent Pipeline"]
  node_agentcore["Support Agent<br/>orchestrator<br/>[agent.ts]"]
  node_intent["Intent Classifier<br/>LLM stage"]
  node_prompt["Support Prompt<br/>LLM policy<br/>[systemPrompt.ts]"]
  node_executor["Tool Executor<br/>tool mediator<br/>[toolExecutor.ts]"]
  node_accuracy["Accuracy Check<br/>background LLM stage"]
  node_anthropic{{"Anthropic Claude<br/>external LLM"}}
  node_openai{{"OpenAI<br/>external LLM"}}
end

subgraph group_tools["Support Tools"]
  node_tools["Support Toolset<br/>business tools<br/>[tools.ts]"]
  node_eligibility["Return Policy Logic<br/>return rules"]
  node_records[("Prototype Business Records<br/>orders and returns data<br/>[orders.ts]")]
end

subgraph group_state["Durable State"]
  node_conversation[("Conversation Store<br/>SQLite store")]
end

subgraph group_notifications["Return Notifications"]
  node_confirmation["Return Confirmation<br/>confirmation workflow<br/>[confirmation.ts]"]
  node_email["Email Delivery<br/>Resend integration"]
end

node_cli["Local CLI<br/>entrypoint<br/>[index.ts]"]

node_cli -->|"local messages"| node_agentcore
node_server -->|"inbound webhook"| node_webhook
node_webhook -->|"validate"| node_signature
node_webhook -->|"parse"| node_payload
node_webhook -->|"deduplicate"| node_dedupe
node_webhook -->|"accepted message"| node_agentcore
node_agentcore -->|"load and append turns"| node_conversation
node_agentcore -->|"classify"| node_intent
node_intent -->|"intent model call"| node_anthropic
node_agentcore -->|"build reply context"| node_prompt
node_agentcore -->|"invoke approved actions"| node_executor
node_executor -->|"dispatch"| node_tools
node_tools -->|"evaluate return"| node_eligibility
node_tools -->|"read or update"| node_records
node_agentcore -->|"generate reply"| node_anthropic
node_agentcore -.->|"background check"| node_accuracy
node_accuracy -.->|"evaluate response"| node_openai
node_agentcore -->|"send reply"| node_osis
node_tools -->|"return created"| node_confirmation
node_confirmation -->|"deliver or record"| node_email

click node_cli "https://github.com/timifaloye/bookly-support-agent/blob/main/src/index.ts"
click node_server "https://github.com/timifaloye/bookly-support-agent/blob/main/src/server.ts"
click node_webhook "https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/webhookHandler.ts"
click node_signature "https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/signature.ts"
click node_payload "https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/webhookPayload.ts"
click node_dedupe "https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/sqliteDedupeTracker.ts"
click node_osis "https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/client.ts"
click node_agentcore "https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/agent.ts"
click node_intent "https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/intentClassifier.ts"
click node_prompt "https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/systemPrompt.ts"
click node_executor "https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/toolExecutor.ts"
click node_accuracy "https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/hallucinationCheck.ts"
click node_conversation "https://github.com/timifaloye/bookly-support-agent/blob/main/src/state/sqliteConversationStore.ts"
click node_tools "https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/tools.ts"
click node_eligibility "https://github.com/timifaloye/bookly-support-agent/blob/main/src/tools/returnEligibility.ts"
click node_records "https://github.com/timifaloye/bookly-support-agent/blob/main/src/data/orders.ts"
click node_confirmation "https://github.com/timifaloye/bookly-support-agent/blob/main/src/lib/confirmation.ts"
click node_email "https://github.com/timifaloye/bookly-support-agent/blob/main/src/lib/resendEmailClient.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_server,node_webhook,node_signature,node_payload,node_dedupe,node_osis toneBlue
class node_agentcore,node_intent,node_prompt,node_executor,node_accuracy,node_anthropic,node_openai toneAmber
class node_tools,node_eligibility,node_records toneMint
class node_conversation toneRose
class node_confirmation,node_email toneIndigo
class node_cli toneNeutral
```

## Components

### OSIS Messaging

- [Webhook Server](https://github.com/timifaloye/bookly-support-agent/blob/main/src/server.ts): entrypoint · `src/server.ts`
- [Webhook Handler](https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/webhookHandler.ts): OSIS adapter · Validates, parses, logs, and deduplicates inbound events. · `src/osis/webhookHandler.ts`
- [Signature Validation](https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/signature.ts): webhook security · `src/osis/signature.ts`
- [Webhook Payload Parser](https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/webhookPayload.ts): webhook parser · `src/osis/webhookPayload.ts`
- [Webhook Dedupe](https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/sqliteDedupeTracker.ts): SQLite tracker · Preserves inbound idempotency across restarts. · `src/osis/sqliteDedupeTracker.ts`
- [OSIS Client](https://github.com/timifaloye/bookly-support-agent/blob/main/src/osis/client.ts): messaging client · Outbound SMS/iMessage boundary. · `src/osis/client.ts`

### Agent Pipeline

- [Support Agent](https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/agent.ts): orchestrator · Coordinates classification, reply generation, and background accuracy checking. · `src/claude/agent.ts`
- [Intent Classifier](https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/intentClassifier.ts): LLM stage · `src/claude/intentClassifier.ts`
- [Support Prompt](https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/systemPrompt.ts): LLM policy · `src/claude/systemPrompt.ts`
- [Tool Executor](https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/toolExecutor.ts): tool mediator · Keeps model logic from directly mutating business data. · `src/claude/toolExecutor.ts`
- [Accuracy Check](https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/hallucinationCheck.ts): background LLM stage · Asynchronously evaluates generated responses. · `src/claude/hallucinationCheck.ts`
- **Anthropic Claude**: external LLM
- **OpenAI**: external LLM · Required application LLM integration, likely used for accuracy evaluation.

### Support Tools

- [Support Toolset](https://github.com/timifaloye/bookly-support-agent/blob/main/src/claude/tools.ts): business tools · Verification, order status, return eligibility, and return creation. · `src/claude/tools.ts`
- [Return Policy Logic](https://github.com/timifaloye/bookly-support-agent/blob/main/src/tools/returnEligibility.ts): return rules · `src/tools/returnEligibility.ts`
- [Prototype Business Records](https://github.com/timifaloye/bookly-support-agent/blob/main/src/data/orders.ts): orders and returns data · `src/data/orders.ts`

### Durable State

- [Conversation Store](https://github.com/timifaloye/bookly-support-agent/blob/main/src/state/sqliteConversationStore.ts): SQLite store · Persists customer and channel conversation turns. · `src/state/sqliteConversationStore.ts`

### Return Notifications

- [Return Confirmation](https://github.com/timifaloye/bookly-support-agent/blob/main/src/lib/confirmation.ts): confirmation workflow · `src/lib/confirmation.ts`
- [Email Delivery](https://github.com/timifaloye/bookly-support-agent/blob/main/src/lib/resendEmailClient.ts): Resend integration · Records confirmations when Resend is not configured. · `src/lib/resendEmailClient.ts`

### Other components

- [Local CLI](https://github.com/timifaloye/bookly-support-agent/blob/main/src/index.ts): entrypoint · `src/index.ts`

## Connections

- Local CLI → Support Agent: local messages
- Webhook Server → Webhook Handler: inbound webhook
- Webhook Handler → Signature Validation: validate
- Webhook Handler → Webhook Payload Parser: parse
- Webhook Handler → Webhook Dedupe: deduplicate
- Webhook Handler → Support Agent: accepted message
- Support Agent → Conversation Store: load and append turns
- Support Agent → Intent Classifier: classify
- Intent Classifier → Anthropic Claude: intent model call
- Support Agent → Support Prompt: build reply context
- Support Agent → Tool Executor: invoke approved actions
- Tool Executor → Support Toolset: dispatch
- Support Toolset → Return Policy Logic: evaluate return
- Support Toolset → Prototype Business Records: read or update
- Support Agent → Anthropic Claude: generate reply
- Support Agent → Accuracy Check: background check
- Accuracy Check → OpenAI: evaluate response
- Support Agent → OSIS Client: send reply
- Support Toolset → Return Confirmation: return created
- Return Confirmation → Email Delivery: deliver or record