How It Works

Chatmancer is a fully serverless application that lives inside your AWS account. This page explains the architecture, the data flow on every chat message, and exactly what Chatmancer can and cannot see.

Architecture overview

Your visitor's browser
        │
        ▼
  Amazon CloudFront  ──────────────────────────────────────────┐
  (CDN + TLS)                                                  │
        │                                                      │
        ├── /dashboard/*  ──▶  S3 (React SPA)                 │
        ├── /widget.js    ──▶  S3 (widget bundle)             │
        └── /api/*        ──▶  API Gateway                    │
                                    │                          │
                                    ▼                          │
                             AWS Lambda                        │
                          (Hono API server)                    │
                                    │                          │
                    ┌───────────────┼───────────────┐          │
                    ▼               ▼               ▼          │
              PostgreSQL         Amazon S3      OpenAI API     │
           (RDS / Aurora)    (documents,        (external)     │
         conversations,       embeddings)                      │
         chatbot config,                                       │
         knowledge base                                        └──▶ chatmancer.com
                                                                    (license check-in
                                                                     once per day)

All resources inside the box are provisioned inside your AWS account. The only external calls are to the OpenAI API (using your key) and a once-daily license check-in to chatmancer.com.

What happens on every chat message

1. The visitor types a message in the widget embedded on your page.
2. The widget sends the message to your API Gateway endpoint over HTTPS.
3. API Gateway triggers your Lambda function.
4. Lambda retrieves the chatbot configuration and conversation history from your RDS database.
5. If the chatbot has a knowledge base, Lambda runs a semantic search against your embeddings stored in S3/RDS to find relevant context.
6. Lambda calls the OpenAI API with the system prompt, retrieved context, and conversation history, using your API key.
7. The response streams back through Lambda → API Gateway → widget → visitor's screen.
8. The exchange is saved to your database.

At no point does any message pass through Chatmancer's infrastructure (except the daily license check-in, which contains no conversation data).

What Chatmancer cannot see

The daily license check-in sends only: your license key hash, a timestamp, and the AWS region. No conversation data, no user data.

AWS Free Tier coverage

For most small-to-medium deployments, Chatmancer runs entirely within the AWS Free Tier:

RDS (PostgreSQL) is the one service that may incur a small cost beyond free tier for high-traffic deployments. You can monitor your bill at any time via the CloudWatch dashboard that ships with the stack.