This directory is the starting point for agents and maintainers. It explains the system at the level needed to make safe changes; source code, tests, database migrations, and the generated API reference remain authoritative.

Read this first

RedditBot is a stateful, multi-account outreach and conversation application. It discovers eligible Reddit posts, prepares AI-generated openers, sends them through Reddit's Matrix chat service, follows replies under bounded policies, records outcomes, and exposes an authenticated operator dashboard and agent API.

The most important operational fact is that local and production configuration may be live-capable. Installing dependencies, building, and testing are safe. Starting the backend, invoking control endpoints, importing sessions, sending messages, or deploying may affect real Reddit accounts and requires explicit authorization.

Documentation map

Document	Use it when
Product goals and safety	You need the purpose, product boundaries, eligibility policy, or definition of success.
Architecture	You need the system shape, process lifecycle, dependency boundaries, or repository map.
Runtime flows	You are changing discovery, screening, candidate delivery, replies, chat sync, media, or realtime updates.
Human-led conversation learning	You are changing attribution, credit, review, retrieval, evaluation, rollout, or framework integration.
Service map	You need to find the module that owns a responsibility or identify extension seams.
Data model	You are changing persistence, migrations, account scoping, idempotency, or analytics.
Configuration	You are adding a setting, changing precedence, or diagnosing startup validation.
API	You are using or changing HTTP/MCP operations. This file is generated.
Frontend	You are changing the React dashboard, shared contracts, queries, routes, or SSE behavior.
Development and testing	You are setting up locally, implementing a change, or choosing verification commands.
Deployment and operations	You are diagnosing or performing Docker/Dokploy work, backups, recovery, or live verification.

Fast orientation by task

Candidate selection or outreach: read product-and-safety, data-flow, services, and database.
Conversation automation: read product-and-safety, data-flow, and the conversation state/claim sections in database.
Dashboard/API work: read frontend, api, and architecture.
Authentication or account work: read architecture, configuration, database, and deployment.
Production incident: read deployment first, then the flow and service that own the failing state.
Schema or config change: read database/configuration and update both transport contracts and tests where applicable.

Sources of truth

Use this order when facts conflict:

Observable behavior and focused tests.
Shared Zod transport contracts in packages/api-contracts/src/.
Runtime Zod configuration in src/config/index.ts and migrations in src/database/client.ts.
Owning implementation under src/ or apps/dashboard/src/.
Generated docs/api.md and live /api/openapi.json.
Narrative documentation in this directory.

Documentation should explain why boundaries exist and where behavior lives. Avoid copying entire schemas, hard-coded production identifiers, current counts, or secrets into prose.

Keeping documentation current

Every code change must include the documentation changes needed to keep this map accurate. In particular:

Add or remove links here when documents change.
Update architecture and service ownership when dependencies move.
Update runtime flows when ordering, eligibility, retries, or idempotency changes.
Update configuration and data model documents with schema changes.
Run npm run docs:api after modifying src/web/api-catalog.ts.
Keep historical plans out of current-state documents; use Git history for retired designs.

See the repository-level agents.md for the mandatory agent workflow.