Source Map

All paths are relative to the pivot repo root unless otherwise stated. Branch of record: development-2.

Repo locations on this machine

Repo	Path
pivot (main)	/Users/alexandresauvedeguise/Dev/pivotteam/pivot
pivot-mia-docs (this site)	/Users/alexandresauvedeguise/Dev/pivotteam/pivot-mia-docs
Pivotmobile	/Users/alexandresauvedeguise/Dev/pivotteam/Pivotmobile

There is no standalone mia-tips or pivot-agent repo / folder. Earlier docs referenced these — they were wrong.

Backend (Firebase Functions, modular monolith)

Area	Path	Notes
Architecture conventions	CLAUDE.md	Module boundaries, layer import rules, OOP/functional split. Always re-read before refactoring.
AI memory module	functions/modules/ai-memory/	Profile, rules, cron tasks.
Router (mounted)	functions/modules/ai-memory/endpoints/apis/router.ts
Sub-router (ai-memory)	functions/modules/ai-memory/endpoints/apis/ai-memory.router.ts
Temporal scheduler service	functions/modules/ai-memory/services/temporal-scheduler.service.ts	Mirrors cron tasks to Temporal.
Chat module (employee messaging)	functions/modules/chat/	Not the AI chat.
Companies module	functions/modules/companies/	Includes ai-tips-rules, ai-usage, ai-config sub-routers.
AI usage + config endpoints	functions/modules/companies/endpoints/apis/ai-usage.router.ts	/companies/:id/ai-usage, /ai-usage/all, /ai-config/*. Admin-gated via inline isAdmin(), not companyScopeMiddleware.
AI tip rules endpoints	functions/modules/companies/endpoints/apis/ai-tips-rules.router.ts	/companies/:id/ai-tips-rules*.
Docs module	functions/modules/docs/	OpenAPI spec generator + Scalar UI. Now self-registered (/openapi.json, /docs, /).
OpenAPI registry	functions/modules/docs/logic/registry.ts	Single source of truth for the API spec. Live: 20 tag groups, 88 paths (17 modules + auth + integration-engine, plus roles as a sub-tag of companies).
Docs router	functions/modules/docs/endpoints/apis/docs.router.ts	/openapi.json, /docs, /.
Calculator module	functions/modules/calculator/	Deterministic arithmetic primitive. Mounted as calculatorApi.
Onboarding module	functions/modules/onboarding/	Session-state endpoints. Auth via x-user-token header.
Requests module	functions/modules/requests/	Shift-request CRUD.
POS-sync module	functions/modules/pos-sync/	Roster sync glue.
Auth system	functions/systems/auth/	Password reset, signup, invitations, impersonation. Hono router; outside modules/ but registered in OpenAPI. DTOs: common/dtos/auth/.
Integration engine	functions/integration-engine/	Generic plugin sync engine (connect, disconnect, trigger sync, OpenTable partner flow). Distinct from the integrations module (which is the catalog).
Shared middleware	functions/shared/middleware/	Auth, scope, claim, logger, trace, errorHandler.
Auth middleware	functions/shared/middleware/auth.middleware.ts
Company-scope middleware	functions/shared/middleware/company-scope.middleware.ts
Request context builder	functions/shared/infrastructure/request-context-from-token.ts

AI service (Cloud Run)

Area	Path
Service root	functions/pivotAiAgent/
Express entrypoint	functions/pivotAiAgent/index.ts
Intent classifier	functions/pivotAiAgent/intent.ts
Tool-loop pipeline	functions/pivotAiAgent/pipeline.ts
Chat-path responder	functions/pivotAiAgent/chat.ts
Onboarding pipeline (also handles MIA Tips)	functions/pivotAiAgent/onboarding-pipeline.ts
Onboarding prompts	functions/pivotAiAgent/onboarding-prompts.ts
Onboarding intent	functions/pivotAiAgent/onboarding-intent.ts
AI config resolution	functions/pivotAiAgent/ai-config.ts
Pricing/usage	functions/pivotAiAgent/pricing.ts
Firebase Admin token helpers	functions/pivotAiAgent/firebase-admin-token.ts
globalThis.fetch interceptor for RTDB	functions/pivotAiAgent/firebase.ts

AI service — its own internal docs

The AI service has its own docs folder (separate from this site, much older, still uses the "Finn" name throughout). Useful for legacy context but treat with skepticism — much of it predates the modular monolith.

File	Path
Architecture overview (Finn-named)	functions/pivotAiAgent/ARCHITECTURE.md
Firebase schema notes	functions/pivotAiAgent/FIREBASE_SCHEMA.md
Migration plan	functions/pivotAiAgent/FIREBASE_MIGRATION.md
In-service docs folder	functions/pivotAiAgent/docs/ — 01-ai-agent-architecture.md, 03-temporal.md, 04-dashboard-layout-and-modals.md, etc.

AI service — tools

Area	Path
Tools registry + dispatcher	functions/pivotAiAgent/tools/index.ts (TOOL_CATALOG, executeTool)
Endpoint URL builder + auth headers	functions/pivotAiAgent/tools/_endpoints.ts
Per-category tool implementations	functions/pivotAiAgent/tools/<category>/<tool>.ts

Tool categories (folders): ai-memory, applicants, attendance, calculator, chat, company, documents, employees, onboarding, posts, requests, research, sales, schedule, tips-rules, weather.

AI service — providers

Area	Path
Provider dispatcher	functions/pivotAiAgent/providers/index.ts
Anthropic adapter	functions/pivotAiAgent/providers/anthropic.ts
OpenRouter adapter	functions/pivotAiAgent/providers/openrouter.ts

AI service — temporal

Area	Path
Worker	functions/pivotAiAgent/temporal/worker.ts
Workflows	functions/pivotAiAgent/temporal/workflows.ts
Activities	functions/pivotAiAgent/temporal/activities.ts
Scheduled reminder	functions/pivotAiAgent/temporal/scheduled-reminder.ts

Frontend

Surface	Path
Main chat	src/routes/PivotAiAgentDashboard/
MIA Tips	src/routes/MiaTips/
AI Onboarding	src/routes/AIOnboarding/
Settings	src/routes/AccountSettings/PivotAiAgent/

Data store rules

File	Owns
firestore.rules	Firestore access (mostly read-only to clients).
database.rules.json	RTDB access.
firestore.indexes.json	Firestore composite indexes.

Build / deploy

File	Purpose
Makefile	Local dev orchestration (emulators, Temporal, AI service).
.firebaserc	Project aliases (default, development-2, staging, production).
firebase.json	Hosting + functions deploy config.
functions/build.js	esbuild bundling per module entry point.
functions/package.json	npm scripts for build/test/deploy.