Skip to main content

Pivot MIA Docs

These are the internal engineering docs for MIA — the AI assistant inside Pivot. End users see it branded as "Mia"; in the code you'll also see it referred to as pivotAiAgent (and in older comments, Finn).

Dev-2 only

Mia is currently deployed only in the pivot-dev-2 environment. No production deploy yet, no staging deploy yet. Every URL, RTDB path, Firebase project, and Cloud Run service in these docs refers to pivot-dev-2. There's no Mia at pivot-inc (production) or pivot-not-production-project (staging).

If you see a pivot-dev-59310 reference, that's the legacy dev project being phased out — also not where current Mia runs.

All content here is sourced from the pivot repository on the development-2 branch. If a section sounds vague or aspirational, treat it as stale — the source is authoritative.

What MIA actually is​

A two-part backend serving a few frontend surfaces:

  • Firebase Functions modular monolith (functions/modules/) — every backend module ships its own Hono router. The ai-memory module owns MIA's persistence (learned company facts, manager rules, cron-scheduled report tasks). 17 modules + 2 sibling Hono systems (auth, integration-engine) — all registered in the auto-generated OpenAPI spec (20 tag groups, 88 paths live on dev-2).
  • Cloud Run service (functions/pivotAiAgent/) — the AI pipeline itself: intent routing, Sonnet tool loop, parallel Haiku fan-out, streaming SSE responses, plus the Temporal worker that runs scheduled reports.
  • 60 tools (functions/pivotAiAgent/tools/) — what the LLM can do. Most tools HTTP-call the same internal Pivot endpoints a normal user would, forwarding the caller's Firebase token, so the AI inherits user-level permissions automatically. See Tool Catalog.
  • Temporal — schedules cron tasks and provides observability for in-flight chat pipelines. Task queue: pivot-ai-agent.

Frontend surfaces live under pivot/src/routes/:

  • PivotAiAgentDashboard/ — the main chat ("Chat with Mia")
  • MiaTips/ — manager-led setup for tip-distribution rules
  • AIOnboarding/ — guided new-owner setup conversation
  • AccountSettings/PivotAiAgent/ — admin/settings

The API is self-documenting​

The backend builds its OpenAPI 3.1 spec at boot from Zod DTOs registered in functions/modules/docs/logic/registry.ts. Two ways to consume:

  • Interactive Scalar UI — /api-reference (gated by this site's @pivotapp.ca OAuth wall)
  • Raw JSON — /api/openapi.json (committed snapshot, refreshed via npm run fetch-openapi-spec)

The upstream cloudfunctions.net/docs endpoint is locked down — Bearer-token required. The embedded viewer above is the canonical engineer-facing path.

These docs intentionally don't duplicate the endpoint schemas — see API Endpoints for the high-level tour and a link to the live spec.

Where to start​

What is not in these docs​

  • Secrets, keys, or any .env contents.
  • Marketing/product copy — only engineering-relevant facts.
  • Endpoint schemas — the live OpenAPI spec is the source of truth.
  • Anything not currently in the development-2 branch of pivot. If you find a stale reference, fix it (the "Edit this page" link points to GitHub).