firestore data model

• client/rules-visible paths are covered by firestore.rules and can be read or written by browser or agent Firebase clients when the rule allows it.
• server-only Admin SDK paths are intentionally denied by rules, or fall through to the deny-all rule. Route handlers, Cloud Functions, and server workers use the Admin SDK for these paths.
• legacy paths still exist for older dashboard, agent, or Cortex flows but are not the model new docs should teach first.
• current public API paths are the storage models behind public API routes. API routes enforce auth and scope before touching Firestore.

client/rules-visible

These paths are explicitly matched in firestore.rules.

firestore/
|-- sites/{siteId}
|   |-- machines/{machineId}
|   |   |-- commands/pending
|   |   |-- commands/completed
|   |   |-- screenshots/{screenshotId}
|   |   |-- installed_software/{softwareId}
|   |   |-- hardware/{docId}
|   |   `-- metrics_history/{bucketId}
|   |-- deployments/{deploymentId}
|   |-- installer_templates/{templateId}
|   |-- project_templates/{templateId}
|   |-- project_distributions/{distributionId}
|   |-- roosts/{roostId}
|   |   |-- versions/{versionId}
|   |   `-- target_state/{machineId}
|   |-- webhooks/{webhookId}
|   |-- logs/{logId}
|   |-- audit_log/{entryId}
|   `-- settings/{settingId}
|-- config/{siteId}
|   |-- machines/{machineId}
|   |-- schedule_presets/{presetId}
|   |-- reboot_presets/{presetId}
|   `-- project_distribution_presets/{presetId}
|-- users/{userId}
|   |-- api_keys/{keyId}
|   |-- settings/{settingId}
|   `-- devicePrefs/{docId}
|-- installer_metadata/{document=**}
|-- system_presets/{presetId}
|-- api_keys/{keyHash}
|-- agent_tokens/{tokenId}
|-- agent_refresh_tokens/{tokenHash}
|-- device_codes/{phrase}
`-- chats/{chatId}
    `-- messages/{messageId}

sites/{siteId}

Top-level site document. Site reads require canAccessSite(siteId). Direct create, update, and delete are service-account only.

sites/{siteId}/machines/{machineId}

Machine presence, status, metrics, process status, reboot state, live-view state, and capability flags live on the machine document itself. There are no current presence or status child documents.

Agents can read and write only their own machine document. Site members can read machine documents for sites they can access. Control-plane writes from the web go through API routes.

Current metrics use schema version 2 and are nested on the machine document:

Legacy singular metrics.cpu, metrics.disk, and metrics.gpu are deleted by current agents after writing v2 metrics. The dashboard still shims older cached shapes during rollout windows.

sites/{siteId}/machines/{machineId}/commands/{commandDoc}

Command queues use two singleton documents:

• commands/pending
• commands/completed

Each document stores command IDs as top-level map fields. A pending document looks like this:

{
  "restart_DESKTOP01_1712000000000": {
    "type": "restart_process",
    "status": "pending",
    "createdAt": "<server timestamp>",
    "expiresAt": "<timestamp>",
    "auditCorrelationId": "optional",
    "process_name": "TouchDesigner"
  }
}

Completed, failed, cancelled, and in-progress states are written into commands/completed under the same command ID:

The server writes pending commands with writeCommandFanOut(). The agent listens to commands/pending, processes unseen map entries, writes the result to commands/completed, then deletes the command field from commands/pending.

sites/{siteId}/machines/{machineId}/hardware/{docId}

Hardware profile documents are readable by site members and writable by the agent for its own machine.

hardware/profile uses this shape:

sites/{siteId}/machines/{machineId}/screenshots/{screenshotId}

Screenshot history is written by server APIs after upload. Site members can read the history gallery.

sites/{siteId}/machines/{machineId}/installed_software/{softwareId}

Agent-written software inventory from the Windows registry.

sites/{siteId}/machines/{machineId}/metrics_history/{bucketId}

Daily metric history buckets, keyed by YYYY-MM-DD, are written by Cloud Functions from machine metric updates.

sites/{siteId}/deployments/{deploymentId}

Installer deployment records. Site members can read them. Server APIs create, update, cancel, retry, uninstall, and delete them.

Target status values include pending, closing_processes, downloading, installing, completed, failed, cancelled, and uninstalled.

sites/{siteId}/installer_templates/{templateId}

Site-scoped deployment templates managed through server APIs and dashboard actions.

sites/{siteId}/roosts/{roostId}

The v2 project distribution model. Site members can create roost shells and edit non-pointer metadata. Version pointer changes are server-mediated through API routes.

Direct Firestore create requires name, targets, createdAt, and schemaVersion: 2, and forbids client-supplied version pointer fields. Direct update cannot change pointer fields or schemaVersion.

sites/{siteId}/roosts/{roostId}/versions/{versionId}

Immutable version metadata. Version bodies live in R2, not in this document. Client-side create, update, and delete are denied by rules.

sites/{siteId}/roosts/{roostId}/target_state/{machineId}

Agent-reported per-target reality for roost sync. The agent for the specific machine can create or update its own document; site members can read or delete stale documents.

sites/{siteId}/logs/{logId}

Site-level event logs. This is the current dashboard log collection. It is not under each machine document.

sites/{siteId}/audit_log/{entryId}

Security-boundary audit records. Site admins can read. Direct client writes are denied; server handlers write through audit helpers.

sites/{siteId}/webhooks/{webhookId}

Site-scoped webhook configuration. Site members can read. All writes go through server APIs.

Delivery history is stored under webhook subcollections by server APIs and is not directly covered by a client rules stanza.

sites/{siteId}/settings/{settingId}

Site settings such as shared LLM/Cortex configuration. Site members can read; server APIs write.

Known document IDs include:

• llm
• cortex

config/{siteId}/machines/{machineId}

Process configuration and machine-level persistent settings. Agents can read and write their own config; server APIs also write config changes.

Current process config uses id/processId, name, exe_path, file_path, cwd, priority, visibility, time_delay, time_to_init, relaunch_attempts, launch_mode, derived autolaunch, schedules, and optional schedulePresetId.

config preset collections

users/{userId}

User profile and access metadata. Users can read their own document; superadmins can read every user. Users can self-create only as member. Server APIs manage roles, site assignments, and deletion.

user subcollections

The raw API key hash lookup lives at top-level api_keys/{keyHash} and is server-only.

installer_metadata/{document=**}

Publicly readable installer metadata. Server APIs write latest and version records.

Common documents:

• installer_metadata/latest
• installer_metadata/data/versions/{version}

system_presets/{presetId}

Platform-level deployment preset library. Authenticated users can read. Server APIs create, update, and delete.

server-only Admin SDK

These collections are written or read through server routes, Cloud Functions, or server workers. Direct browser and agent access is denied by explicit rules or by the catch-all deny rule.

siteChunks/{digest}

Production chunk bytes live in Cloudflare R2. In emulator/E2E mode, hasChunk() checks this top-level collection instead.

legacy

These paths may still be present during migration windows. New integrations should use the current public API storage models and routes instead.

sites/{siteId}/project_distributions/{distributionId}

Legacy project distribution records. They coexist with roost v2 during the cutover but are not the current project sync model.

sites/{siteId}/project_templates/{templateId}

Legacy reusable project distribution templates. Current roost upload/publish flows do not depend on this path.

config/{siteId}/project_distribution_presets/{presetId}

Legacy distribution preset library. It remains rules-visible for older UI flows and built-in preset overrides.

chats/{chatId} and chats/{chatId}/messages/{messageId}

Legacy Cortex conversation storage. Rules still expose this collection to the owning user, and older Cortex categorization paths still read/write it.

Messages under messages/{messageId} contain role, content, and createdAt.

legacy/local Cortex bridge paths

Older local Cortex bridge code references these paths:

• sites/{siteId}/machines/{machineId}/cortex/active-chat
• sites/{siteId}/cortex-events/{eventId}
• sites/{siteId}/cortex-state/lock

They are not the current public chat API storage model. Treat them as legacy dashboard/agent internals unless the owning Cortex code is explicitly being updated.

machine-level log shipping

The older log-shipping helper attempts to write sites/{siteId}/machines/{machineId}/logs/{logId}. Current rules do not define that subcollection, and current dashboard activity logs use sites/{siteId}/logs/{logId}.

current public API

These storage models sit behind public API routes. Clients should call the API surface rather than reading or writing these collections directly.

public chat storage

Current public Cortex chat APIs use chat_conversations/{conversationId}. The most recent messages are embedded on the conversation document; older messages spill to chat_conversations/{conversationId}/chat_messages/{messageId} after the embedded array reaches 200 entries.

Embedded and spilled message rows contain:

roost quota and usage

Quota and usage storage is server-managed. Public routes such as GET /api/sites/{siteId}/quota and GET /api/sites/{siteId}/quota/history expose scoped views.

roost version bodies and chunk bytes

Firestore stores roost metadata and pointers only. Actual version bodies and chunk bytes live in R2:

The Firestore roosts/{roostId}/versions/{versionId} document records metadata and the R2 URL; it does not contain the full version body.