Firestore Data Model
Firestore is the control plane for users, jobs, entitlements, application configuration, audit records, and coach relationships. Large video and report objects live in Cloud Storage; their paths are stored in Firestore.
The executable source of truth is acesense-frontend/firestore.rules plus the
writers in acesense-auth-function. This page is an orientation map, not a
schema migration system.
Core collections
| Collection | ID | Purpose | Client access |
|---|---|---|---|
users | Firebase UID | profile, consent, entitlement, usage, onboarding | owner read; profile/consent fields only for owner writes |
jobs | server-generated | upload, orchestration, status, result references | owner read; presentation fields only for owner updates |
sessions | generated | user-created session history | owner read/write |
users/{uid}/notifications | generated | analysis-ready and account notifications | owner read; owner may change only read |
config | named document | public app-version gate and admin configuration | config/app public-read; other access admin-only |
requestUploadPath is the only app-side job creator. Session deletion goes
through deleteSession so the job and private Storage artifacts are removed
together.
Commerce and operations
| Collection | Purpose | Write owner |
|---|---|---|
api_keys | hashed API-key metadata, balance, usage | Cloud Functions |
api_keys/{id}/rate_buckets | minute/day rate accounting | Cloud Functions |
api_keys/{id}/balance_adjustments | balance audit trail | admin callables |
billing_events | idempotent billing-webhook receipts | Cloud Functions |
pending_plan_grants | deferred account grants | Cloud Functions |
link_codes | download/campaign redirect registry | admins |
download_clicks | redirect attribution events | Cloud Functions |
Coach mode
| Collection | Purpose | Read access |
|---|---|---|
coaches | coach profile and seat state | that coach or admin |
coachLinks | two-party coach/player consent state | either party or admin |
coachNotes | append-only coach feedback | linked coach/player or admin |
Mutations go through callables. An active link does not widen direct reads of a
player's users or sessions documents; server callables broker that access.
Feedback, mail, and audit data
feedback: authenticated app submissions; append-only to the client.docs_feedback: private-docs feedback written bydocsServer.client_errors: bounded client-side diagnostic events.mail: server-only Trigger Email queue.signed_url_audit,moderation_audit, andadmin_audit: server-written, admin-readable audit trails.
User document ownership
Users may change profile and UX fields such as display name, locale, tennis profile, notification preferences, onboarding state, and AI consent. Plan, tier, trial dates, subscription limits, usage counters, suspension state, and other entitlement fields are server-owned. Treat the rule allowlist as authoritative whenever a new field is added.
Job relationship
See Job Document for the job state contract and Security Model for rule boundaries.