jjbrunton/RedditBot
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: describe React dashboard migration state

Browse Source
This commit is contained in:
jjbrunton committed 2026-08-08 15:32:38 +01:00
1 parent 720e5e3e34
commit 12a853fa42
6 files changed
+194 -95
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/architecture.md
+66 -23
View File
@@ -41,7 +41,7 @@
| Response Monitoring | Background service checks inbox for user replies |
| Chat Automation | Reddit chat scraping via shadow DOM traversal, auto-reply support |
| Media Management | Download, cache, deduplicate, and sync media from conversations |
| Web Dashboard | Real-time monitoring with SSE log streaming, analytics, and controls |
| Web Dashboard | React operator console with typed SSE events, analytics, and guarded controls |
---
@@ -101,9 +101,9 @@
│
▼
┌─────────────────────────────────────────────────────────┐
│ Web Dashboard (Express) │
│ React Dashboard + Express API/SSE host │
│ │
│ 25+ API endpoints │ SSE log streaming │ Analytics │
│ Typed contracts │ SSE events │ Analytics │
│ Runtime config │ Bot controls │ Media gallery │
└─────────────────────────────────────────────────────────┘
```
@@ -161,8 +161,14 @@ RedditBot/
├── Dockerfile # Container build definition
├── package.json # Node.js dependencies & scripts
├── tsconfig.json # TypeScript configuration
├── apps/
│ └── dashboard/ # React, TypeScript, React Router, and Vite
│ ├── src/ # Shell, routes, feature slices, API clients
│ └── dist/ # Generated production assets (not committed)
├── packages/
│ └── api-contracts/ # Shared Zod HTTP and realtime schemas
├── public/
│ └── index.html # Single-file web dashboard (HTML+CSS+JS)
│ └── index.html # Temporary legacy dashboard fallback
├── scripts/
│ ├── inspect-chat-dom.ts # Debug: inspect chat DOM structure
│ └── login.ts # Manual browser login helper
@@ -196,7 +202,9 @@ RedditBot/
│ ├── retry.ts # Exponential backoff wrapper (28 lines)
│ └── image.ts # Image download + base64 + MIME validation (34 lines)
└── web/
└── server.ts # Express dashboard + SSE streaming (794 lines)
├── server.ts # Express API, SSE, and dashboard host
├── dashboard-assets.ts # React-build selection with legacy fallback
└── events/ # Typed event hub and Express SSE adapter
```
---
@@ -206,6 +214,7 @@ RedditBot/
### Core Services
#### MonitorService (`src/services/monitor.ts`)
Discovers new image posts across configured subreddits.
- Shuffles subreddit order each cycle
@@ -214,6 +223,7 @@ Discovers new image posts across configured subreddits.
- Returns the single newest valid post per cycle
#### ProcessorService (`src/services/processor.ts`)
Core processing pipeline for each discovered post.
1. Downloads image via `ImageService`
@@ -224,6 +234,7 @@ Core processing pipeline for each discovered post.
6. Handles AI refusals gracefully (marks post, tries next)
#### StrategySelector (`src/services/strategy-selector.ts`)
Implements explore/exploit A/B testing for message variants.
- Tracks response rates per strategy variant
@@ -232,6 +243,7 @@ Implements explore/exploit A/B testing for message variants.
- Selects best variant based on weighted response rates
#### ResponseChecker (`src/services/response-checker.ts`)
Background service that monitors for user replies.
- Navigates Reddit inbox via Playwright
@@ -240,6 +252,7 @@ Background service that monitors for user replies.
- Stores successful message/response pairs for few-shot learning
#### ChatService (`src/services/chat.ts`)
Most complex service - manages Reddit chat interactions.
- Scrapes `chat.reddit.com` using JavaScript injection (shadow DOM traversal)
@@ -251,6 +264,7 @@ Most complex service - manages Reddit chat interactions.
- Parameter: `myUsername` is hardcoded (should be from config)
#### MediaService (`src/services/media.ts`)
Media download, caching, and indexing.
- Downloads images from chat conversations
@@ -260,6 +274,7 @@ Media download, caching, and indexing.
- Tracks download status per conversation
#### MediaSyncService (`src/services/media-sync.ts`)
Periodic background media synchronization.
- Runs incremental syncs (top 10 chats) or full syncs (all conversations)
@@ -268,6 +283,7 @@ Periodic background media synchronization.
- Exposed via web dashboard endpoints
#### AutoReplyService (`src/services/auto-reply.ts`)
Automated reply to Reddit chat conversations.
- Checks for unread messages in cached conversations
@@ -279,6 +295,7 @@ Automated reply to Reddit chat conversations.
### External Integrations
#### RedditApi (`src/reddit/api.ts`)
Axios-based Reddit API client.
- Fetches posts from subreddits (`/r/{name}/new.json`)
@@ -288,6 +305,7 @@ Axios-based Reddit API client.
- Uses Playwright browser cookies for authenticated requests
#### OpenRouterService (`src/ai/openrouter.ts`)
OpenRouter API client using OpenAI-compatible SDK.
- `analyzeImage()`: Multi-model image analysis with fallback chain
@@ -298,6 +316,7 @@ OpenRouter API client using OpenAI-compatible SDK.
- Refusal detection via heuristic patterns
#### Browser Client (`src/browser/client.ts`)
Playwright persistent context manager.
- Browser session persistence (cookies/storage)
@@ -306,6 +325,7 @@ Playwright persistent context manager.
- Debug screenshot capture on login failure
#### MessagePage (`src/browser/message-page.ts`)
Reddit DM compose page automation.
- Fills recipient/subject/body fields
@@ -316,6 +336,7 @@ Reddit DM compose page automation.
### Data Layer
#### Database Client (`src/database/client.ts`)
Better-SQLite3 database initialization.
- Creates database at configured path
@@ -324,6 +345,7 @@ Better-SQLite3 database initialization.
- Safe column-addition for schema evolution
#### Repositories (`src/database/repositories.ts`)
Three repository classes abstracting SQLite operations.
- **PostsRepository**: Processed post CRUD, mark sent, update analysis
@@ -333,6 +355,7 @@ Three repository classes abstracting SQLite operations.
### Utilities
#### Logger (`src/utils/logger.ts`)
Winston structured logging.
- JSON format for log files
@@ -340,6 +363,7 @@ Winston structured logging.
- File logging: `error.log` and combined log
#### RateLimiter (`src/utils/rate-limiter.ts`)
Token-bucket rate limiting.
- p-queue with concurrency=1
@@ -348,6 +372,7 @@ Token-bucket rate limiting.
- Timer status exposed to dashboard
#### Retry (`src/utils/retry.ts`)
Exponential backoff wrapper.
- p-retry with configurable retries (default 3)
@@ -355,6 +380,7 @@ Exponential backoff wrapper.
- Logging on retries and failures
#### Image (`src/utils/image.ts`)
Image processing utilities.
- Download via axios
@@ -364,15 +390,33 @@ Image processing utilities.
### Web Dashboard
#### WebServer (`src/web/server.ts`)
Express server with 25+ API endpoints.
Express server with API route modules and SSE transport.
- Stats, activity, messages, chats, conversations, media endpoints
- Bot controls (start/stop)
- SSE realtime log streaming
- Typed resumable events at `/api/events/stream`
- Temporary legacy log stream at `/api/logs/stream`
- Analytics: strategy, subreddit, daily trends
- Runtime config management (GET/PUT)
- Debug endpoints
#### React dashboard (`apps/dashboard`)
- React Router routes Overview, Conversations, Media, Performance, Operations,
and Settings.
- TanStack Query owns authoritative HTTP snapshots and mutation state.
- Feature-local clients validate responses with schemas from
`packages/api-contracts`.
- Operations consumes typed dashboard events and invalidates affected query
keys; cached content remains visible if the stream reconnects.
- Vite writes production assets to `apps/dashboard/dist`.
The asset resolver prefers the React build and can fall back to
`public/index.html`. Wiring that resolver into authenticated Express static and
private-media hosting is still a migration gate; the legacy file has not been
removed.
---
## Data Flow
@@ -597,7 +641,8 @@ All endpoints are served by the Express server at `http://localhost:{port}`.
| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/logs/stream` | SSE realtime log stream |
| GET | `/api/events/stream` | Typed resumable SSE event stream |
| GET | `/api/logs/stream` | Temporary legacy SSE log stream |
| GET | `/api/logs` | Recent logs (HTTP) |
| GET | `/api/timers` | Rate limiter timer status |
| POST | `/api/debug/inspect-dom` | Debug: inspect chat DOM structure |
@@ -744,16 +789,14 @@ Configuration and database creation use factory functions:
### Observer Pattern
SSE (Server-Sent Events) for realtime log streaming:
SSE (Server-Sent Events) carries validated dashboard events:
```typescript
// Logger writes to a shared buffer
logger.info("Message sent to user123");
// The transport-agnostic hub assigns IDs and retains a bounded replay window.
eventHub.publish({ type: "message.sent", payload: { /* validated fields */ } });
// WebServer subscribes clients via SSE
app.get("/api/logs/stream", (req, res) => {
// Push new log entries to connected clients
});
// Express adapts the hub to resumable SSE.
router.get("/events/stream", broadcaster.events);
```
### Circuit Breaker / Retry
@@ -827,7 +870,7 @@ class RateLimiter {
The project includes full Docker support:
- **`Dockerfile`** - Multi-stage build with Node.js
- **`Dockerfile`** - Playwright image with browser, VNC, and frontend/server build tooling
- **`docker-compose.yml`** - Service orchestration
- **`.dockerignore`** - Excludes unnecessary files
@@ -849,7 +892,7 @@ Deployment documentation is provided in `DOKPLOY_DEPLOY.md`.
1. Set up `config.yaml` with target subreddits and settings
2. Set environment variables (or use `.env` file)
3. Run `npm install` to install dependencies
4. Run `npm run build` to compile TypeScript
4. Run `npm run build` to compile the server and Vite dashboard
5. Run `scripts/login.ts` once to establish browser session
6. Start the bot (via `npm start` or Docker)
@@ -859,10 +902,8 @@ Deployment documentation is provided in `DOKPLOY_DEPLOY.md`.
### Critical
1. **No Tests** - Zero test coverage. Add unit tests for services, especially:
- `StrategySelector` (complex algorithm)
- `ChatService` (shadow DOM logic)
- `OpenRouterService` (model fallback logic)
1. **Dashboard security cutover** - Wire authenticated React asset, API, SSE,
debug, and private-media hosting before exposing the dashboard externally.
2. **No README.md** - No project documentation for new developers.
@@ -881,9 +922,11 @@ Deployment documentation is provided in `DOKPLOY_DEPLOY.md`.
### Medium Priority
7. **Single-Page Dashboard** - `public/index.html` is ~2000+ lines with embedded CSS/JS. Consider a proper frontend framework.
7. **Legacy dashboard fallback** - `public/index.html` remains during migration.
Remove it only after authenticated React hosting and feature-parity gates pass.
8. **WebServer Size** - 794 lines. Consider splitting routes into separate files.
8. **Settings route** - The React route is still a placeholder; runtime and
access settings have not yet moved into validated route-backed forms.
9. **Config Mutability** - Runtime config updates via `PUT /api/config` modify the in-memory config object. Consider a proper config service with validation on updates.