Builder docs
System architecture, contracts, runbooks. For builders adding agents, workflows, or wiring TikTok Army into a new client.
System Architecture
High-level shape of the TikTok Army backend, the major modules, and how data flows from a brief submission through a workflow run, agent step, trace persistence, and dashboard render.
Agent Contract
The `BaseAgent` class, the `run()` vs `_execute()` split, `AgentContext` / `AgentResult`, contextvars for tracing, and which of three patterns each of the 15 agents follows.
Workflow Contract
`WorkflowDef` + `WorkflowStepDef`, the special node types (`APPROVAL_NODE`, `SYNTHESIS_NODE`), `input_map` dotted paths, the topo sort, and where the runner persists state.
Trace Pipeline
The relationship between `tiktok_agent_runs`, `tiktok_agent_steps`, and `tiktok_workflow_steps`; what each captures; how `lib.claude.call_claude_cached` writes a trace row; how the SSE stream works; mock vs real mode.
Adding a New Agent
Step-by-step: subclass `BaseAgent`, add to `AGENT_REGISTRY`, write an `AgentSpec` in `_catalog.py`, add fixtures to `mock_claude._FIXTURES`, optionally seed it into a workflow.
Adding a New Workflow
Define a `WorkflowDef` in `orchestrator/definitions.py`, append it to `SEEDED_WORKFLOWS`, optionally add a synthesis fixture to `mock_claude._SYNTHESIS_FIXTURES`, and what to test.
Deploy Runbook
Local dev (uvicorn + next dev with mock mode), Postgres on WSL, env vars for real mode, GCP deploy via `deploy.sh` + `dashboard/deploy.sh`, Secret Manager, alembic migrations.
Testing
pytest with `asyncio_mode=auto`, mock mode means no API key needed for tests, what tests exist today vs what's missing, and how to run a workflow end-to-end in mock mode for verification.