Architecture — Cross-Cutting Design

clients
  id              uuid PK
  name            text unique               -- kebab-case, e.g. "internal-projectX"
  display_name    text
  is_owner        bool                      -- exactly one row may have this true
  disabled_at     timestamptz null          -- gates all auth when set
  metadata        jsonb
  created_at      timestamptz default now()
  -- partial unique (is_owner) WHERE is_owner enforces single-owner

api_keys
  id                 uuid PK
  client_id          uuid FK clients(id) ON DELETE CASCADE
  label              text                    -- "claude-desktop-laptop"
  prefix             text unique             -- 12 chars, indexed lookup column
  hash               bytea                   -- 32B HMAC-SHA256(pepper, full token)
  scopes             jsonb                   -- array of scope strings, see §3
  rpm_limit          int not null default 60
  daily_msg_limit    int not null default 250
  expires_at         timestamptz null        -- hard cut-off
  revoked_at         timestamptz null        -- soft delete
  rotated_from_id    uuid null               -- self-FK; rotation lineage
  last_used_at       timestamptz null        -- updated async (batched)
  last_used_ip       inet null
  created_at         timestamptz default now()
  -- indexes: unique(prefix), partial (client_id) WHERE revoked_at IS NULL,
  --          partial (expires_at) WHERE expires_at IS NOT NULL

phone_numbers
  id                          uuid PK
  wa_phone_number_id          text unique not null      -- Meta's numeric id
  wa_business_account_id      text not null
  display_number              text                      -- E.164 with +, humans only
  label                       text
  access_token_secret_ref     text                      -- "secrets://wa_access_token_<id>"
  webhook_verify_token_ref    text                      -- per-number to limit blast radius
  disabled_at                 timestamptz null
  created_at                  timestamptz default now()
  -- NOTE: no app_secret column. App Secret is per Meta App, not per number.
  -- All numbers in this WABA share the App Secret read from WA_APP_SECRET
  -- (secrets://wa_app_secret). If we ever split into multiple Meta Apps,
  -- add a nullable app_secret_ref column then.

client_phone_grants     -- M:N — what each client may do with which number
  id                  uuid PK
  client_id           uuid FK clients(id)
  phone_number_id     uuid FK phone_numbers(id)
  allowed_tools       jsonb not null            -- e.g. ["send_message","get_messages"]
  daily_message_cap   int null                  -- override of api_keys.daily_msg_limit
  revoked_at          timestamptz null
  created_at          timestamptz default now()
  -- unique (client_id, phone_number_id) WHERE revoked_at IS NULL

contacts
  id                 uuid PK
  phone_number_id    uuid FK phone_numbers(id)
  wa_id              text not null              -- E.164 with no leading +
  profile_name       text                       -- from Meta contacts[].profile.name
  display_name       text                       -- local override
  metadata           jsonb
  first_seen_at      timestamptz default now()
  last_seen_at       timestamptz default now()
  -- unique (phone_number_id, wa_id)

messages
  id                 uuid PK
  phone_number_id    uuid FK phone_numbers(id)
  client_id          uuid FK clients(id)        -- nullable for inbound (number-owned)
  direction          text                       -- 'inbound' | 'outbound'
  wa_message_id      text unique                -- Meta's wamid.xxx
  contact_id         uuid FK contacts(id)
  message_type       text                       -- text|template|image|document|audio|video|sticker|reaction|interactive
  body               text                       -- plaintext for text/caption
  template_name      text null
  media_object_id    uuid FK media_objects(id) null
  status             text                       -- queued|sent|delivered|read|failed (out); received|read (in)
  error_code         int null
  reply_to_wamid     text null
  payload            jsonb                      -- normalised body (e.g. interactive selectedId)
  raw                jsonb                      -- original Meta payload (inbound), sanitised
  ts                 timestamptz                -- Meta event time
  created_at         timestamptz default now()
  -- indexes: unique(wa_message_id),
  --          (phone_number_id, ts DESC),
  --          (client_id, ts DESC) WHERE direction='outbound',
  --          (phone_number_id, contact_id, ts DESC) WHERE direction='inbound'

media_objects
  id                 uuid PK
  phone_number_id    uuid FK phone_numbers(id)
  direction          text                       -- inbound|outbound
  wa_media_id        text                       -- Meta media id (inbound)
  mime_type          text
  sha256             bytea
  size_bytes         bigint
  storage_path       text                       -- relative under MEDIA_ROOT, never absolute
  downloaded_at      timestamptz null           -- null for outbound
  created_at         timestamptz default now()

audit_log                  -- append-only; app role has INSERT,SELECT only
  id                 bigserial PK
  ts                 timestamptz default now()
  client_id          uuid FK clients(id) ON DELETE SET NULL null
  api_key_id         uuid FK api_keys(id) ON DELETE SET NULL null
  request_id         text                       -- propagated through Inngest
  ip                 inet null
  user_agent         text null
  action             text                       -- see action vocabulary below
  tool_name          text null
  phone_number_id    uuid FK phone_numbers(id) ON DELETE SET NULL null
  wa_message_id      text null
  payload_hash       bytea null                 -- SHA-256 of canonicalised input
  error_code         text null
  latency_ms         int null
  metadata           jsonb null
  -- indexes: (client_id, ts DESC), (api_key_id, ts DESC), (action, ts DESC),
  --          (wa_message_id) WHERE wa_message_id IS NOT NULL, BRIN on ts

rate_limit_buckets         -- token bucket
  id              uuid PK
  key             text                          -- 'rpm:<api_key_id>:<minute>' or 'daily:<client_id>:<phone>:<hour>'
  window_start    timestamptz
  count           int not null default 0
  updated_at      timestamptz default now()
  -- unique (key, window_start); partial index on stale rows for GC

inngest_idempotency        -- dedupe Meta webhook retries
  event_id        text PK                       -- wamid for inbound, our request-id for outbound
  first_seen_at   timestamptz default now()
  outcome         text                          -- processed|duplicate|failed

Nginx (TLS, strips client X-Forwarded-* / X-Real-Ip, adds X-Request-Id)
  → Express trust proxy = 1
  → request-id middleware (CLS / AsyncLocalStorage propagation into Inngest)
  → body parser (express.raw on /webhook/*, express.json on /mcp/*)
  → authMiddleware
       parse Bearer wamcp_live_...
       lookup api_keys by 12-char prefix
       HMAC-SHA256(pepper, token) constant-time compare against hash
       attach req.auth = { clientId, apiKeyId, scopes, rpmLimit, dailyMsgLimit }
       fail-closed: any error here → 401
  → client-enabled check (clients.disabled_at IS NULL)
  → per-key RPM rate-limit check (Postgres sliding window)
  → MCP dispatcher (validates JSON-RPC envelope)
  → tool layer:
       parse input via tool's zod schema
       requireScope(toolName)              -- key has tools:<name> or tools:*
       requireGrant(clientId, phoneNumberId, toolName)
                                           -- client_phone_grants row exists,
                                           --   not revoked, contains toolName
       (outbound only) per-client daily-cap check
       run tool body
  → response post-processor (audit log emit + rate-limit bucket increment)

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1715000060

# Meta
WA_GRAPH_API_VERSION=v23.0
WA_APP_SECRET=                 # X-Hub-Signature-256, per Meta App (shared by all numbers in the App)
WA_WEBHOOK_VERIFY_TOKEN=       # v1 single-number convenience; per-number tokens via phone_numbers.webhook_verify_token_ref later
WA_DEFAULT_PHONE_NUMBER_ID=    # v1 single number convenience
WA_DEFAULT_WABA_ID=
WA_DEFAULT_ACCESS_TOKEN=

# Server
APP_PUBLIC_URL=https://wa.<yourdomain>
APP_HTTP_PORT=3000
APP_BIND=127.0.0.1
MCP_TRANSPORT=http             # 'http' | 'stdio'
NODE_ENV=production
LOG_LEVEL=info

# Postgres
DATABASE_URL=postgres://wa:***@postgres:5432/wa_mcp

# Inngest Cloud
INNGEST_EVENT_KEY=
INNGEST_SIGNING_KEY=
INNGEST_SERVE_PATH=/api/inngest

# Media
MEDIA_ROOT=/var/lib/whatsapp-mcp/media
MEDIA_SIGNING_SECRET=          # HMAC for signed download URLs
MEDIA_URL_TTL_SECONDS=300

# Auth
API_KEY_PEPPER=                # 32 random bytes, base64-encoded
LOCAL_OWNER_CLIENT_ID=         # uuid of the is_owner=true row

# Rate limits (defaults; overridable per-key/grant in DB)
RL_DEFAULT_RPM=60
RL_DEFAULT_DAILY_MSGS=250
RL_OWNER_RPM=600
RL_OWNER_DAILY=10000