Skip to content

Email Submissions

A concise guide to the Email Submissions system: what it does, how the parts fit together, and how to contribute high-quality documentation.

System Architecture

The diagram below shows the end-to-end flow.

Customers send email submissions to out Managed Inbox. Upon recieveing the email, our Managed Inbox pushes notifications to our Watcher service. Our Watcher service wakes up, finds the new emails, and enqueues them all for processing. The Email Handler service dequeues this work and processes the email. Processed emails are ready to be sent back to the originating customer. The Email Handler handles the sending.

AI Submissions Architecture

At a glance:

  • Managed Inbox:
  • Watcher:
  • Email Handler:
  • Watch Manager:
  • Synthetic Client:

Writing Good Docs

  • Diátaxis: Docs should do only 1 of these 4:
    • Tutorials: Learning-oriented, step-by-step introductions.
    • How-to Guides: Task-oriented procedures for specific goals.
    • Reference: Accurate, technical descriptions of modules, APIs, and schemas.
    • Explanations: Context, architecture rationale, ADRs, and design trade-offs.
  • The Good Docs Project Templates

Conventions we use:

  • Reference docs are generated from Python docstrings via mkdocstrings.
  • API docs are generated from FastAPI's and APIFlask's OpenAPI specification via scripts/generate_openapi_specs
  • Diagrams live under docs/internal/assets/diagrams/ and are embedded as SVG.

Preview

Local preview (macOS):

source .venv/bin/activate
mkdocs serve -a 127.0.0.1:8001

Versioning & Building with mike

This site uses Mike for versioned documentation (integrated with MkDocs Material’s version selector).

Common commands:

# Preview all versions locally (use this over mkdocs serve for versions)
mike serve

# Create initial version and mark as latest
mike deploy 0.1 latest --push
mike set-default latest --push

# Release a new version and keep the latest alias updated
mike deploy 0.2 latest --update --push

# Optional helpers
mike list
mike alias 0.2 stable --push
mike retitle 0.2 "0.2 (Jan 2026)" --push

Deployment on Vercel

  • Deployment is handled by Vercel from the gh-pages branch generated by Mike.
  • Pushing with --push in the Mike commands updates gh-pages and triggers a Vercel deploy.
  • The project includes a minimal Vercel config in the repo root (vercel.json). In Vercel settings:
    • Production Branch: gh-pages
    • Framework: Other (no build step)
    • Output Directory: . (site is prebuilt by Mike)

For single-version local development, mkdocs serve is fine. For multi-version preview and parity with production, use mike serve.