# Agent Guidelines & Code Standards

## Refactoring Goal
Refactor code to improve maintainability, testability, and clarity. Break down large components into smaller, single-purpose classes/modules.

## Engineering Standards
### 1. Single Responsibility Principle (SRP)
- Avoid "God Classes" (e.g., massive `Service` classes that do everything).
- Extract logic into dedicated handlers, managers, or utilities.
- **Example**: Instead of one `BotService` handling login, monitoring, and messaging, split into `AuthService`, `MonitorService`, and `MessagingService`.

### 2. Design Patterns
- **Dependency Injection**: Pass dependencies via constructors. This makes swapping implementations (e.g., for testing) easier.
- **Factory Pattern**: Use factories for creating complex objects (e.g., configuring different AI models).
- **Strategy Pattern**: Good for interchangeable algorithms (e.g., differentsubreddit selection strategies).

### 3. TypeScript Best Practices
- **Strict Typing**: No `any`. Define interfaces/types for all data structures (especially API/Reddit responses).
- **Zod Validation**: Use `zod` (already in deps) to validate external data (config files, API responses).
- **Async/Await**: properly handle promises. Use `p-queue` or `p-retry` for rate-limited operations.

### 4. Testing
- TDD is not required. Agents may implement changes before writing or updating tests.
- Add or update tests when they provide useful coverage for new functionality or bug fixes.
- Tests live in `tests/` (mirroring `src/` structure) and run via `vitest` (`npm test`).
- Prefer behavior-focused tests (inputs → outputs / observable side effects) over tests that pin internal structure.

### 5. Project Specifics
- **Tech Stack**: Node.js, TypeScript, Playwright, Express, SQLite, Vitest.
- **Directories**: 
  - `src/services/` for business logic.
  - `src/web/` for Express server and UI.
  - `src/browser/` for Playwright interactions.
  - `tests/` for vitest specs, mirroring `src/` layout.
- **Logging**: Use `winston` for structured logging. Do not use `console.log` in production code.

## Workflow for Agents
1. **Analyze**: Before writing code, read the file and understand the context.
2. **Plan**: Identify what needs to change and check if the change violates SRP.
3. **Implement**: Make the scoped change. Create new small files when SRP calls for it.
4. **Test**: Add or update useful tests as appropriate for the change.
5. **Refactor**: Tidy the implementation and tests while preserving behavior.
6. **Verify**: Run the relevant tests and type checks (`npm run build` or `tsc --noEmit`) in proportion to the change.

You must use the dokploy credentials in .env for access to dokploy