Architecture

Whilst is a monorepo containing a Next.js web application, AWS Lambda services, and shared TypeScript packages orchestrated via pnpm workspaces.

High-Level Architecture

┌──────────────────────────────────────────────────────────┐
│  Slack Workspace                                          │
│  User mentions @whilst → Slack Events API                 │
└────────────────────┬─────────────────────────────────────┘
                     ▼
┌──────────────────────────────────────────────────────────┐
│  AWS (Backend Services)                                   │
│                                                           │
│  API Gateway ──► Event Intake Lambda                      │
│                    ├─ Validates Slack signatures           │
│                    ├─ Normalises events                    │
│                    └─ Enqueues to SQS                      │
│                          ▼                                │
│                    SQS Queue                               │
│                          ▼                                │
│                  Job Worker Lambda                         │
│                    ├─ Resolves workspace credentials       │
│                    ├─ Calls MCP adapters                   │
│                    ├─ Runs Knowledge Pipeline              │
│                    └─ Publishes Slack updates              │
│                          ▼                                │
│              Neon Postgres (pgvector)                      │
└──────────────────────────────────────────────────────────┘
                     ▼
┌──────────────────────────────────────────────────────────┐
│  Vercel (Web Application)                                 │
│  Next.js 14 App Router                                    │
│    ├─ Document management (TipTap editor)                 │
│    ├─ AI Sidekick (chat, search, actions)                 │
│    ├─ WorkOS authentication                               │
│    └─ Real-time sync (AWS AppSync Events)                 │
└──────────────────────────────────────────────────────────┘

Component Map

Communication Adapters

Normalise events from Slack (future: Discord, Teams) into a channel-agnostic format and publish to the intake Lambda via API Gateway.

Event Intake Lambda

Validates adapter-specific request signatures (Slack X-Slack-Signature)
Converts raw events into NormalisedEvent payloads
Enqueues SQS jobs
Responds within 3 seconds

Job Worker Lambda

Triggered by SQS (batch size 1 for ordering)
Resolves per-workspace credentials
Sends acknowledgement via communication adapter
Calls MCP client adapter and streams status updates
Implements retry/backoff on 429/5xx
Updates Postgres and pushes audit events

MCP Client Library

Shared TypeScript package with typed adapters per source (GitHub, Linear, Notion). Normalises responses into { answer, citations[], raw }.

Credential Resolver

Multi-tenant credential lookup from AWS Secrets Manager. Provides per-workspace auth tokens with caching for the duration of a job.

Web Application (Next.js 14)

Server Components + App Router
TipTap rich text editor
pgvector semantic search
React Query + Zustand state management
WorkOS authentication
Deployed on Vercel

Persistence Layer

PostgreSQL (Neon) — primary database with pgvector extension
Workspace configs, encrypted credentials, documents, embeddings, jobs
All keyed by workspace_id for tenant isolation

Observability

CloudWatch logs/metrics
X-Ray tracing across Lambdas, SQS, Postgres
DLQ for SQS with replay Lambda
Slack alerts via SNS

Data Flow

User mentions @whilst

User asks a question in Slack, e.g. “What’s the latest open PR about churn?”

Event intake

Slack sends app_mention to API Gateway. Intake Lambda verifies signature, persists job stub, enqueues SQS item, responds 200.

Job processing

Job Worker pulls the message, resolves workspace credentials, sends acknowledgement to Slack.

MCP query + Knowledge Pipeline

MCP adapter fetches data (e.g. GitHub PRs). Knowledge Pipeline analyzes the thread for topics, decisions, and action items.

Response delivered

Final answer posted as Slack thread update. Auto-generated doc saved to Postgres. Job marked complete.

Monorepo Structure

whilst-slack-bot/
├── apps/
│   └── web-app/              # Next.js 14 (main UI)
├── services/
│   ├── event-intake/         # Lambda: Slack event ingestion
│   ├── job-worker/           # Lambda: Background job processor
│   └── user-resolver/        # Lambda: User context resolution
├── packages/
│   ├── shared/               # Shared utilities, types
│   ├── communication-slack/  # Slack API client
│   ├── mcp-clients/          # MCP integrations
│   ├── tenant-store/         # Workspace data access layer
│   ├── job-store/            # Job queue management
│   └── knowledge-pipeline/   # Thread analysis + auto-doc
├── infra/                    # AWS CDK infrastructure
└── docs/                     # Technical documentation

Data Model

Key tables in the PostgreSQL schema:

Table	Purpose
`workspaces`	Slack workspace registrations and bot tokens
`tenant_accounts`	Multi-tenant account/organization records
`tenant_users`	User accounts within tenants
`jobs`	Job queue tracking (requested → complete)
`docs`	Generated documents with embeddings
`conversations`	Ingested Slack thread metadata
`messages`	Individual thread messages
`actors`	Participant identities
`relationships`	Collaboration graph edges
`mcp_credentials`	Per-workspace MCP source credentials
`api_keys`	MCP Server API keys

Getting Started

Features

Guides

Development

High-Level Architecture

Component Map

Communication Adapters

Event Intake Lambda

Job Worker Lambda

MCP Client Library

Credential Resolver

Web Application (Next.js 14)

Persistence Layer

Observability

Data Flow

Monorepo Structure

Data Model

​High-Level Architecture

​Component Map

​Communication Adapters

​Event Intake Lambda

​Job Worker Lambda

​MCP Client Library

​Credential Resolver

​Web Application (Next.js 14)

​Persistence Layer

​Observability

​Data Flow

​Monorepo Structure

​Data Model

High-Level Architecture

Component Map

Communication Adapters

Event Intake Lambda

Job Worker Lambda

MCP Client Library

Credential Resolver

Web Application (Next.js 14)

Persistence Layer

Observability

Data Flow

Monorepo Structure

Data Model