Jamie BruntonandClaude Opus 5
1ac6ad22ad
A new Reddit account cannot start chats until Reddit considers it established, and nothing in the app previously did anything about that. Account growth posts a small number of AI-written comments per day on active threads in an operator-chosen list of communities, per account, so the history that lifts the hold actually accumulates. Growth is account-scoped rather than part of the shared outreach funnel: karma, comment history and pacing all belong to one identity. It runs as the lowest-priority work in the account runtime, after inbound replies, and deliberately keeps running while an account is held out of outbound messaging. Comments publish without operator review, so the guards are the feature: - Both screening stages fail closed. A deterministic gate rejects links, contact solicitation, user tags, filler and any text that reveals the generator; the classifier must actively approve with confidence, and an outage stalls growth rather than publishing unreviewed text. - Thread text reaches the model only as fenced untrusted data, since Reddit posts do contain instructions aimed at automated readers. - The daily allowance is adaptive, not configured: it starts at two per day and rises only while comments survive and earn upvotes. - Posted comments are swept at ~15m/2h/24h with one batched info.json request, plus a single signed-out probe that detects a comment the public cannot see. Two consecutive removals, an invisible comment, or a captcha challenge pauses the account until an operator clears it. A failed probe never pauses anything. - One comment per thread across every owned account, enforced by a unique index, because two of our accounts on one post is the easiest pattern to correlate. - A comment interrupted mid-post is abandoned, never retried: we cannot know whether the write landed and a duplicate cannot be withdrawn. - Reddit's refusals are authoritative — a ban disables that community for that account, a throttle backs off at the scope Reddit named, and a signed-out response invalidates the session. Comments are submitted through the account's own browser session against the old.reddit form endpoint, which returns machine-readable error codes and needs no credentials beyond the cookies already imported. API-first: /api/growth exposes state, settings, the community list and pause/resume, all verified against a local instance. Route responses are parsed with the shared contracts in tests so the server-side mirror cannot drift from what the dashboard expects. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
RedditBot documentation
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. |
| 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.tsand migrations insrc/database/client.ts. - Owning implementation under
src/orapps/dashboard/src/. - Generated
docs/api.mdand 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:apiafter modifyingsrc/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.