ShadeStudio: frontend, backend and MCP architecture

CREATE TABLE refresh_token (
  id          uuid PRIMARY KEY,
  family_id   uuid NOT NULL,
  customer_id uuid NOT NULL REFERENCES customer(id),
  token_hash  bytea NOT NULL UNIQUE,   -- never the raw token
  used_at     timestamptz,
  revoked_at  timestamptz,
  expires_at  timestamptz NOT NULL
);
CREATE INDEX refresh_family ON refresh_token (family_id);

CREATE TABLE token_denylist (
  jti        uuid PRIMARY KEY,
  expires_at timestamptz NOT NULL     -- row ends with the token
);

• Presenting a token that has used_at set revokes the whole family_id.

CREATE TABLE audit_log (
  ts timestamptz NOT NULL, trace_id text,
  sub text, channel text, tool text,
  stage text, decision text,
  args_hash bytea, latency_ms integer
) PARTITION BY RANGE (ts);           -- monthly

• token_denylist is mirrored in Redis, so the per-call jti check never touches PostgreSQL. Rows expire with the token.
• audit_log: monthly partitions, insert-only role (REVOKE UPDATE, DELETE), arguments stored only as a hash.
• Agent tokens are never stored: they live in agent memory for 5 minutes.

// 1. hold_slot result becomes a UI event
event: ui.confirm
data: {"holdId":"hold_81f","priceMinor":180000,
       "expiresAt":"2026-10-10T11:50:00Z"}

// 2. customer taps Confirm: browser to BFF (cookie + CSRF)
mutation { confirmHold(holdId: "hold_81f") { token } }

// 3. agent to MCP server
tools/call confirm_booking
  { "holdId": "hold_81f", "confirmationToken": "eyJ…" }

{ "sub": "cus_2041", "hold": "hold_81f", "price_minor": 180000,
  "ch": "web", "jti": "c7f1…", "exp": now+120 }

• Signature valid, not expired, sub equals the access token's sub
• Hold still live and owned; price unchanged since read-back
• jti unused: SET ctok:{jti} 1 NX EX 120
• Voice and WhatsApp: the channel adapter mints it after a full spoken read-back and a clear yes, or a quick-reply bound to the hold id

Gateway returns 429 + Retry-After. Inside MCP: isError with RATE_LIMITED and retryAfterMs, so the agent backs off.

-- KEYS[1] = rl:{dim}:{id}   ARGV: now_ms, emission_ms, burst_ms
local tat = tonumber(redis.call('GET', KEYS[1]) or ARGV[1])
tat = math.max(tat, tonumber(ARGV[1]))
local new = tat + tonumber(ARGV[2])
local over = new - tonumber(ARGV[1]) - tonumber(ARGV[3])
if over > 0 then return {0, over} end   -- limited, retry in `over` ms
redis.call('SET', KEYS[1], new, 'PX', ARGV[3] + ARGV[2])
return {1, 0}

• Dimensions: ip, sub, device, phone, conversation
• Reads fail open on Redis error. Writes fail closed.
• Result surfaces as 429 + Retry-After, or RATE_LIMITED inside MCP.

-- KEYS: hold:{slot}, holds:{sub}
-- ARGV: sub, ttl_s, cap, now_ms, exp_ms
redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', ARGV[4])  -- prune
if redis.call('ZCARD', KEYS[2]) >= tonumber(ARGV[3]) then
  return 'HOLD_LIMIT'
end
if not redis.call('SET', KEYS[1], ARGV[1], 'NX', 'EX', ARGV[2]) then
  return 'SLOT_TAKEN'
end
redis.call('ZADD', KEYS[2], ARGV[5], KEYS[1])
return 'OK'

• Cap and claim happen together, so parallel tool calls cannot exceed 2 holds.
• Redis down: holds are refused, confirms still check the database constraint.

{ "ts": "2026-10-10T11:44:02Z", "trace_id": "4bf92f35…",
  "actor": { "sub": "cus_2041", "channel": "web",
            "session": "mcps:5c0e9a", "jti": "a91b…" },
  "tool": "confirm_booking",
  "args_hash": "sha256:9d1c…",        // args are hashed, not stored
  "stage": "execute", "decision": "allow",
  "idempotency_key": "7c1e…",
  "result": { "booking_id": "BK-20931" }, "latency_ms": 412 }

• Span per stage: mcp.auth, mcp.policy, mcp.confirm, handler, redis, payments
• Audit rows are append-only and shipped to immutable storage.