Baton system map

One shared record from identity to release.

This public diagram documents product boundaries without exposing deployment identifiers, credentials, account data, or private project records.

01

Runtime boundary

Public rendering, authenticated data, and optional providers remain separate.

  1. Browser or installed appLoads the mobile-first full-width shell with dedicated content scrolling and safe-area-aware chrome.
  2. Next.js on VercelServes public pages, static/PWA assets, metadata, health, secret sealing, and the optional AI route. Offline cache never serves tenant/auth/API data.
  3. Convex CloudOwns Auth, tenant RBAC, functions, data, encrypted provider rows, fixed provider verification, platform control-plane data, Public API, and MCP transport.
  4. Optional providersGoogle, email delivery, and AI remain disabled until their complete credentials are configured.

02

Developer and client flow

A secure invitation carries context and a precise role into the same project record.

  1. Developer profileCreates or joins a workspace and starts a project.
  2. Delivery contractCaptures brief, canonical scope, IN and OUT boundaries, questions, QA, and phase.
  3. Secure invitationBinds a hashed, expiring, revocable, single-use token to an email and role.
  4. Client authenticationUses password or Google; the verified normalized email must match the invitation.
  5. Direct membershipCreates workspace context and direct project access atomically.
  6. Shared decisionsClient reviews, asks or answers questions, and posts updates within allowed capabilities.
  7. Release handoffDeveloper moves the delivery record through QA and shipped without losing the decision trail.

03

Many-to-many data model

Membership rows are the authority; creator fields remain migration compatibility only.

User

Authentication identity linked to one public profile.

Workspace membership

Connects many users to many workspaces with owner, admin, developer, or client roles.

Project membership

Connects many users to many projects with lead, developer, reviewer, or client roles.

Project

Belongs to one workspace and owns delivery state plus provider resource bindings.

Workspace provider account

GitHub, Vercel, Hostinger, or Cloudflare account authority reusable by projects in that workspace; direct secrets are ciphertext and hosted accounts keep broker metadata only.

Project tunnel binding

Binds GitHub repository, Vercel project, Hostinger domain/VPS, Cloudflare zone, and project-scoped Convex deployment authority without exposing provider credentials.

Client onboarding

One project intake record stores contact context, objective, success metrics, systems, guardrails, target date, and completion state.

Commercial record

Invoices belong to one project and carry validated line items plus draft, sent, paid, or void state. Payment collection remains external.

Invitation

Stores token hash, invited email, granted role, expiry, and acceptance or revocation state.

Social graph

Profiles, follows, and public, workspace, or project-scoped posts preserve visibility boundaries.

04

Capability boundary

The UI reflects effective access; Convex re-checks every operation.

Lead

Owns the project boundary and destructive decisions.

  • View project
  • Manage project tunnel
  • Manage onboarding and invoices
  • Edit brief and scope
  • Change phase
  • Review QA
  • Ask and answer questions
  • Invite members
  • Delete project

Developer

Moves delivery work without taking ownership away from the lead.

  • View project
  • Manage project tunnel
  • Manage onboarding and invoices
  • Edit brief and scope
  • Change phase
  • Review QA
  • Ask and answer questions
  • Invite members

Reviewer

Validates work and records review decisions.

  • View project
  • View tunnel readiness
  • View onboarding and invoices
  • Review QA
  • Ask and answer questions

Client

Participates in the decision trail without editing delivery control.

  • View project
  • View tunnel readiness
  • Complete client onboarding
  • View invoices
  • Ask and answer questions
  • Post project updates

05

Multi-project tunnel

Reusable account authority stays separate from project resource authority.

  1. Workspace accountOwner/admin connects GitHub, Vercel, Hostinger, or Cloudflare once. Direct plaintext crosses the authenticated server route once and is sealed before persistence; hosted broker connections store no provider secret.
  2. Authenticated vaultAES-GCM ciphertext is bound to a random credential id. Public queries, logs, API, and MCP never receive cipher or credential id.
  3. Project bindingLead/developer selects a repository, deployment project, domain/VPS, or zone. The project stores validated resource metadata and a reference to the workspace account.
  4. Convex exceptionEach project stores its own encrypted Convex deploy credential because deployment keys are deployment authority.
  5. Fixed executorVerification uses fixed GitHub, Vercel, Hostinger, Cloudflare, and optional Composio hosts/actions—not caller-supplied URLs, methods, MCP endpoints, or Authorization headers.
  6. Hosted fallbackOptional hosted auth is identity-bound and can fall back to same-tab redirect, copied link, retry, or a direct scoped token.
  7. Agent visibilityPublic API and MCP expose sanitized readiness only; connector MCP capability is metadata separate from authentication.

06

MCP and external AI flow

Discovery and execution are both filtered by token scope, binding, membership, and RBAC.

  1. Client registrationRegisters an exact HTTPS or loopback redirect URI.
  2. OAuth consentUser signs in, reviews read or write scope, and completes PKCE S256.
  3. Expiring bearer tokenStored as a hash and optionally bound to one workspace or project.
  4. Filtered catalogtools/list returns only tools allowed by the effective scope, including project intake, commercial lifecycle, and sanitized tunnel-read operations.
  5. Call-time authorizationtools/call re-checks revocation, expiry, binding, membership, and capability.
  6. Bounded operationReads are limited; mutations record safe activity metadata without raw secrets.

07

Platform control plane

Platform visibility is explicit and separate from tenant membership.

  1. Environment rootOne configured account is the super-admin root of trust; optional operators may receive bounded admin or support access.
  2. Global read modelsDedicated queries expose users, workspaces, projects, memberships, activity, errors, and aggregate health without creating tenant roles.
  3. Denormalized analyticsAn hourly job computes bounded platform metrics so an open dashboard does not rescan growing production tables reactively.
  4. Append-only auditPlatform setting and operator changes record actor, action, bounded target metadata, and time without secrets.
  5. Runtime settingsDatabase controls may disable or lower API/MCP scope, rate limits, token lifetime, OAuth registration, analytics, and retention; environment limits always win.
  6. Tenant isolation remainsSuper-admin visibility does not silently grant project edit, phase, document, QA, invite, or delete capabilities.

08

Public API flow

A versioned REST surface uses credentials and activity history separate from MCP.

  1. Issue API keyThe account chooses read or write within the current platform ceiling. Plaintext is shown once; only a hash is stored.
  2. Bearer authenticationEvery request re-checks key expiry, global API state, current maximum scope, and per-user request budget.
  3. Tenant authorizationRead and write handlers execute as the key owner and reuse workspace/project capability checks rather than bypassing them.
  4. Versioned endpointsThe v1 surface exposes profile, workspaces, projects, sanitized project tunnel readiness, client onboarding, invoice lifecycle, and project creation with bounded JSON responses.
  5. Safe activityRoute, method, state, duration, and bounded failure class are retained; bearer values and request bodies are never logged.

09

Shared walkthrough boundary

A dedicated sample identity demonstrates the product without becoming a mutable tenant or polluting real analytics.

  1. Dedicated identityThe shared account is separate from operators and real client workspaces.
  2. Deterministic seedAn internal seed creates one sample workspace with new, active, and shipped engagement states from real product tables.
  3. Server read-onlyOrdinary mutations, invitation delivery, AI spend, deploy controls, API/MCP credential issuance, and OAuth authorization are refused server-side.
  4. Integration isolationEven a stale bearer credential owned by the shared identity cannot resolve through Public API/MCP token lookup or mutate provider connections.
  5. Analytics hygieneSample identity, workspaces, projects, posts, keys, and activity are excluded from adoption and usage aggregates.