Normal

Normal is a personal platform that lets approved AI clients work with a connected WhatsApp account through the Model Context Protocol.

Each User owns one Personal Account. A Personal Account can hold up to three WhatsApp Connections and can grant each MCP Client access to an explicit set of Connections and capabilities. Read access and send access are separate permissions. Every outbound message requires confirmation in the MCP Client.

The platform is currently built for a private beta. Privacy, deletion, auditability, and safe recovery are part of the core design, not optional layers added later.

What is in this repo

This is a Bun and Turbo monorepo with seven deployable apps:

Shared code is split by responsibility:

The API Worker is the public data plane. Provider credentials stay behind the private provider-control service binding. Neon is the authoritative data store, while Cloudflare bindings handle edge protocol state, queues, and encrypted webhook payloads.

Related MCP server: WhatsApp MCP Server

Requirements

You need:

• Bun 1.3.14

• Node.js 20 or newer for supporting tools

• Wrangler through the pinned workspace dependency

• OpenTofu 1.12.5 for infrastructure validation

• Chromium and its host dependencies for browser tests

For local provider or deployment work, you will also need access to the relevant Clerk, Cloudflare, Neon, AWS, Vercel, and Wasender environments.

Local setup

Install the pinned dependencies:

bun install --frozen-lockfile

Create local secret files only for the apps you plan to run:

cp apps/api/.dev.vars.example apps/api/.dev.vars
cp apps/provider-control/.dev.vars.example apps/provider-control/.dev.vars
cp apps/deletion-coordinator/.dev.vars.example apps/deletion-coordinator/.dev.vars
cp apps/restore-coordinator/.dev.vars.example apps/restore-coordinator/.dev.vars
cp apps/recovery-control/.dev.vars.example apps/recovery-control/.dev.vars
cp apps/web/.env.example apps/web/.env.local

The example files document the required values. Never commit .dev.vars, .env.local, credentials, tokens, phone numbers, provider payloads, or decrypted message content.

Start the web app and API Worker together:

bun run dev

You can also run one workspace directly:

bun run --cwd apps/web dev
bun run --cwd apps/api dev
bun run --cwd apps/provider-control dev

If a real external webhook needs to reach your local Worker, run the configured Cloudflare tunnel in another terminal:

bun run dev:tunnel

Verification

CI runs these checks in order:

bun run format:check
bun run lint
bun run typecheck
bun run validate:infra
bun run test
bun run build
bun run manifests:validate
bun run observability:validate
bun run infra:validate

The release and deployed-environment gates are separate from ordinary pull request verification:

bun run launch:gate
bun run release:public-api
bun run deploy:smoke

Install the pinned browser once before the first full test run:

bun x playwright install --with-deps chromium

Tests intentionally exercise production-shaped boundaries. API, provider-control, and recovery-control tests use the pinned Cloudflare Vitest runtime; the deletion and restore coordinator suites use ordinary Vitest. Browser tests use a production Next.js build and a test-only Wrangler API, while database tests apply production migrations in PGlite and switch to restricted runtime roles with RLS. Test composition roots must never become selectable from a production build.

bun run build also dry-runs production Worker bundles and scans Worker, source-map, Next.js, and docs output for test fixtures, controlled credentials, and fault-injection markers.

For focused work, use Turbo filters or workspace commands:

bun x turbo run test --filter=@whatsapp-mcp/api
bun x turbo run typecheck --filter=@whatsapp-mcp/web
bun run --cwd packages/db test

The root test script always runs scripts/*.test.ts before Turbo. Run the API public-boundary composition or one browser journey directly with:

(cd apps/api && bun x vitest run --config vitest.public-boundary.config.ts)
(cd apps/web && bun x playwright test test/browser/api-keys.spec.ts)

Database changes

Database code and versioned production migrations live in packages/db. These commands require the direct TLS Neon owner URL in MIGRATION_DATABASE_URL; never configure it on a deployable app.

bun run --cwd packages/db db:generate
bun run db:migrate
bun run db:check

Do not edit a migration that has shipped. Preserve tenant foreign keys, runtime role grants, fixed search paths, RLS policies, deletion behavior, and restore behavior. Tests must exercise the production migration path.

Generate the public OpenAPI artifact with bun run --cwd packages/contracts generate:openapi. Building apps/docs also regenerates apps/docs/public/openapi.json and copies the pinned Scalar browser asset; do not hand-edit either generated file.

Architecture and operations

Start with these documents:

• CONTEXT.md defines the product language and invariants.

• docs/architecture.md maps the production boundaries and primary data flows.

• docs/mcp-contract.md defines MCP tools, resources, authorization, errors, and pagination.

• docs/configuration.md lists runtime configuration and secret ownership.

• docs/testing.md explains the public boundary test strategy.

• docs/wasender-seam.md defines the provider boundary.

• docs/stored-media-container.md describes encrypted Stored Media.

• docs/adr records architectural decisions.

• docs/runbooks contains deployment, incident, recovery, security, and teardown procedures.

The most important rules are simple:

• Use the terms in CONTEXT.md in code, tests, and docs.

• Keep provider details behind packages/wasender and apps/provider-control.

• Fail closed when identity, authorization, audit, quota, encryption, or configuration is unavailable.

• Never retry an outbound send when provider acceptance is ambiguous.

• Keep logs and telemetry free of message content, credentials, full phone numbers, provider identifiers, and tenant identifiers unless an approved contract explicitly allows them.

• Make deletion and restore behavior explicit for every new persisted record.

Deployment

Development, preview, and production have separate configuration and infrastructure authority. Do not deploy by improvising commands from local manifests.

Follow docs/runbooks/deployment.md, but use the production workflow as the executable deployment order: migrate and check the database, then deploy provider-control, deletion coordinator, restore coordinator, recovery control, the rendered API, web, docs, and finally smoke the release. Production recovery, key rotation, replay, break-glass access, and environment teardown each have dedicated runbooks under docs/runbooks.

Sandcastle

Sandcastle can run issue agents in isolated Docker worktrees. After authenticating Docker, GitHub CLI, and Codex:

bun run sandcastle:build-image
bun run sandcastle

Agent specific issue and triage guidance lives in docs/agents.