Architecture Overview

MIA is split into two backend runtimes plus a set of React frontend surfaces. The split exists because the AI pipeline (long-running, streaming, model-heavy) doesn't fit Firebase Functions' execution model, but the persistence and scheduling logic does.

Runtime split

Note the CR → FF arrow: MIA tools call internal Firebase Function endpoints over HTTP, forwarding the user's Firebase token. The AI inherits the user's permissions via the standard middleware. There's a small amount of tech debt where some tools fall back to Admin-SDK direct RTDB writes — only for paths that don't have an endpoint yet. See Agent SDK: exceptions.

• Firebase Functions (functions/) — modular monolith with Hono routers per module. MIA's persistence module is functions/modules/ai-memory/. See the root CLAUDE.md in the pivot repo for the module conventions.
• Cloud Run service (functions/pivotAiAgent/) — separate deploy target (make ai-deploy). Hosts the chat endpoint, the AI pipeline, the Temporal worker, the 60 tools, and the LLM provider adapters.
• Temporal — orchestrates scheduled report tasks and provides observability for in-flight chat pipelines. Single task queue: pivot-ai-agent.

Self-documenting API

All 17 modules register their routes with Zod schemas at functions/modules/docs/logic/registry.ts. The docs module builds an OpenAPI 3.1 spec at boot:

• Interactive Scalar UI — /api-reference (embedded in this site, OAuth-gated)
• Raw JSON — /api/openapi.json (committed snapshot, refreshed via npm run fetch-openapi-spec)

These docs link to the spec rather than duplicate it. See API Endpoints for the module-by-module tour.

Backend modules

17 modules exist under functions/modules/:

schedule, employees, companies (includes ai-tips-rules, ai-usage, ai-config), attendance, payroll, applicants, posts, chat, sales, ai-memory, documents, pos-sync, integrations, calculator, docs, requests, onboarding.

Plus two Hono-based systems that follow the same pattern but live outside functions/modules/:

• auth — functions/systems/auth/
• integration-engine — functions/integration-engine/

All are registered in the OpenAPI spec — the committed snapshot at /api/openapi.json (rendered at /api-reference) currently has 20 tag groups, 88 paths. (The tag count is one more than the module count because the companies module splits into companies + roles tags.) Plus the separately deployed Cloud Run service pivotAiAgent (not in the spec; it's a separate runtime).

Frontend surfaces

All under src/routes/:

Route	Path	Role
Main chat	PivotAiAgentDashboard/	Streaming chat with Mia; widgets + suggestions.
Tip rules	MiaTips/	Manager-led conversation to configure tip-distribution.
Onboarding	AIOnboarding/	Replaces the manual setup wizard for new company owners.
Settings	AccountSettings/PivotAiAgent/	Admin config for MIA.

Data stores

• Firebase RTDB — all MIA persistence (memory, rules, cron tasks, sessions, tip rules). See Data: Memory & Conversations for collection paths.
• Firestore — read-only here. Used only for integration plugin metadata (IntegrationSettings, IntegrationPluginSyncs, etc.). See firestore.rules.
• PostgreSQL — migration in progress (codebase has @google-cloud/cloud-sql-connector and kysely). Several Pub/Sub onXxxPgSync listeners propagate writes from RTDB to PG today.

External dependencies

• Anthropic — primary LLM provider (Haiku 4.5 + Sonnet 4.6). See Provider Selection.
• OpenRouter — fallback / enterprise routing path.
• Brave Search (and DuckDuckGo fallback) — for the web_search tool.
• Open-Meteo — for the get_weather tool. Public, no auth.
• Temporal — Cloud or self-hosted, selected via TEMPORAL_ADDRESS. Local dev runs Temporal in Docker.
• Firebase Admin — for token verification, RTDB I/O, and the Admin-SDK paths used by create_shift and onboarding tools.