Data Model

ArchAgent uses Firestore as its primary datastore. All collection paths are centralized in shared/src/paths.ts -- never construct paths as raw strings.

Entity Relationships

Top-Level Collections

config/platform

Platform-wide configuration singleton.

Field	Type	Description
copilotModel	string	Model for instance copilot
agentModel	string	Default model for custom agents
openclawModel	string	Default model for OpenClaw agents
mastraModel	string	Default model for Mastra agents
maxTokens	number	Max tokens per response

users/{id}

User profiles.

Field	Type	Description
email	string	User email
subscription	object	Stripe subscription state
copilotConversationIds	map	Conversation ID references
usage	object	Usage tracking

users/{id}/private/secrets

Encrypted user secrets (API keys, channel app tokens, integration tokens).

Field	Type	Description
apiKeys	map	Provider API keys (anthropic, openai, google, ollama)
channelApps	map	Channel bot tokens by platform
integrationApps	map	Integration tokens (e.g., GitHub PATs)

instances/{id}

Workspace instances. Each maps to a Cloud Run service.

Field	Type	Description
userId	string	Owner
name	string	Display name
status	string	provisioning, running, stopped, error
cloudRunService	string	Cloud Run service name
topology	Topology	Multi-agent topology configuration
createdAt	timestamp	Creation time
updatedAt	timestamp	Last update

agents/{id}

Agent definitions. Top-level collection, references instanceId.

Field	Type	Description
userId	string	Owner
instanceId	string	Parent workspace
name	string	Display name
agentType	string	openclaw, mastra, or custom
config	AgentConfig	Runtime configuration (name, personality, model provider, channel, integration)
role	string	Agent role description
goal	string	Agent goal
capabilities	string	Agent capabilities
status	string	running, paused, stopped
channelStatus	string	connected, disconnected, error
ocRuntime	object	OpenClaw-specific runtime state
mastraRuntime	object	Mastra-specific runtime state

OpenClaw Runtime Fields (ocRuntime)

Field	Type	Description
ocAgentId	string	OpenClaw agent ID
ocVersion	string	OC binary version
ocModel	string	Current model
ocSkillsInstalled	number	Installed skill count
ocSkillsAvailable	number	Available skill count
ocThinking	string	Thinking level

Mastra Runtime Fields (mastraRuntime)

Field	Type	Description
threadId	string	Conversation thread ID
mcpServers	McpServerConfig[]	Configured MCP servers

Instance Subcollections

Path	Purpose	Key Fields
instances/{id}/sessions	Bridge session tracking	startedAt, status
instances/{id}/commands	Copilot-to-bridge command queue	command, args, status
instances/{id}/activity	Activity log (lifecycle, messages, errors)	type, severity, message, timestamp
instances/{id}/context	Shared context for multi-agent coordination	channel, authorAgentId, content, type
instances/{id}/approvals	Execution approval requests	status, command, agentId
instances/{id}/metrics/aggregate	Aggregated message metrics	counts, timestamps

Context Entry Types

Context entries in instances/{id}/context carry one of four types:

Type	Purpose
artifact	Code, documents, or other outputs
status	Progress updates
decision	Architectural or design decisions
handoff	Work handoff between pipeline stages

Entries are scoped to channels: all, planning, code, review, status.

Agent Subcollections

Path	Purpose	Key Fields
agents/{id}/messages	Chat messages (status machine)	role, content, status, channel, responseContent
agents/{id}/tasks	Structured work items	title, description, status, assignedBy
agents/{id}/memory	Persistent agent memory	type, key, content, metadata
agents/{id}/private/runtime	Agent secrets (channel token, proxy secret)	proxySecret, channelToken
agents/{id}/integrationAudit	Proxy request decision log	method, path, allowed, reason

Message Status Machine

Agent messages follow a strict status progression:

pending --> processing --> complete

Messages arrive as pending, the agent loop marks them processing while working, and writes responseContent when marking complete. Channel adapters watch the same doc via waitForReply -- no second query needed.

Memory Types

Agent memory has five categories:

Type	Purpose	Example Keys
identity	Who the agent is	role, personality, skills, constraints
user_relationship	What it knows about the user	preferences, goals, communication_style
task	Active work state across sessions	current_task, status, blockers, next_steps
knowledge	Learned facts about the domain	repo_structure, architecture, dependencies
team_shared	Visible to all agents in the instance	shared_plan, handoffs, decisions

Firestore Path Reference

All paths are built via shared/src/paths.ts:

import { paths } from "@archagent/shared";

paths.platformConfig()          // "config/platform"
paths.user(userId)              // "users/{userId}"
paths.userSecrets(userId)       // "users/{userId}/private/secrets"
paths.instance(instanceId)      // "instances/{instanceId}"
paths.agents()                  // "agents"
paths.agent(agentId)            // "agents/{agentId}"
paths.agentMessages(agentId)    // "agents/{agentId}/messages"
paths.agentTasks(agentId)       // "agents/{agentId}/tasks"
paths.agentMemory(agentId)      // "agents/{agentId}/memory"
paths.agentSecrets(agentId)     // "agents/{agentId}/private/runtime"
paths.context(instanceId)       // "instances/{instanceId}/context"
paths.approvals(instanceId)     // "instances/{instanceId}/approvals"
paths.integrationAudit(agentId) // "agents/{agentId}/integrationAudit"