Jamie BruntonandClaude Opus 5
725b5fc4e6
Conversations were hard to manage because "unread" came straight from
Matrix's notification_count, and nothing in the app ever sends a read
receipt — so opening a conversation in the dashboard could never clear it
and the unread set only ever grew. The list also collapsed three
orthogonal facts into one word, labelling "they spoke last and we have
not replied" as "Up to date".
Read state is now ours:
- conversation_read_state table (migration 19) plus
ConversationReadStateRepository, kept separate from conversation_states
so a read write can never be lost to mergeConversationState. The
watermark is monotonic, so a stale poll cannot resurrect an unread
badge.
- hasUnreadInbound and needsReply are derived server-side and returned on
every conversation. Matrix's `unread` stays on the contract but the
dashboard no longer reads it.
- POST /conversations/{id}/read|unread|status and
POST /conversations/bulk-read, with optimistic cache updates.
Inbox rework:
- List rows are a real grid (checkbox, open button, chip strip) instead of
a full-bleed absolute overlay button, which previously forced a
pointer-events escape hatch for anything interactive in a row. Rows use
aria-current rather than aria-pressed. Not a listbox: options must not
contain interactive descendants.
- Counted filter pills replace the select, independent state chips replace
the collapsed status word, plus a sort control (including oldest
unanswered), a per-account filter, age-coloured timestamps, and an
explicit count of rows hidden by the seller filter.
- Keyboard: j/k/arrows, Enter, u, e, / and Escape. Shortcuts yield to any
open dialog so Escape dismisses the modal, not the conversation behind
it. Multi-select with bulk mark-read and mark-done.
- Detail panel: auto-mark-read on open, a "New messages" divider pinned at
mount (deriving it from the live watermark made it vanish a second after
opening), triage actions in the header, the automation banner moved out
of the composer, day dividers with time-only stamps, and a flex column
so history scrolls in its own region instead of painting over the
composer.
- Row order freezes while a conversation is open, with a "N new — refresh"
pill, so a background poll cannot reorder rows mid-triage.
Two database tests rewound user_version by an offset from the latest
version, which silently re-targets a different migration whenever one is
appended. They now pin absolute versions.
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.