Jamie BruntonandClaude Opus 5
c43e534cf1
The settings page had accumulated five tabs whose names no longer matched their contents, three different save models, and the whole subreddit configuration buried under a tab named after a checkbox. Structure: - Subreddits becomes its own page: a list showing each community's mode, tone, computed share of polling, and live sent/reply stats, with one subreddit edited at a time in a drawer. - Accounts becomes its own page. It is session lifecycle, not config. - Settings collapses to one scrolling page: Safety, Pacing (Monitoring and Rate limits merged), Targeting, Notifications, Advanced. - The sidebar is grouped, having gone from 9 to 11 destinations. Saving: - Every section owns its own draft, validation, risk gate and save via useConfigCard, submitting only the keys it owns. A syntax error in the advanced JSON can no longer block a rate-limit change, and enabling an autonomous policy is its own deliberate commit. - UnsavedChangesProvider restores the leave-page guard across cards that no longer share a draft. Subreddit editing: - Errors are keyed by field name instead of array index, removing the defensive invalidation that existed because row indices shifted on add and remove. Confirming an autonomous mode can no longer be attributed to the wrong row. - Weight is shown as the share it actually produces, live while editing. - Bulk actions cover start/pause polling, tone, policy and removal, because production runs 30-40 subreddits and per-row editing does not scale. Bulk policy changes name every subreddit turning autonomous, and normalise the hybrid mode's turn budget, which has no form to catch it. Physique targeting moves into its own Targeting card. It sends only reddit.physiqueTargeting, which the config route applies independently, so it cannot clobber the pacing card's fields. Turning screening on now warns that it will reduce how many posts qualify. Also surfaces the effective sending rate, since the hourly limit and the minimum delay both throttle and only the binding one matters. Legacy ?section= links redirect or resolve to anchors. Fixes found while verifying in a browser: a radio-card rule was shrinking nested number inputs; .share-preview had no styles; the throughput readout reported a rate from a blank field; and the reconcile logic warned about a server change whenever a sibling card saved. 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.