ReadMeABook/CLAUDE.md

CLAUDE.md - Project Standards & Workflow

Critical: This document defines AI-optimized documentation standards and development workflow. NEVER PERFORM COMMITS ON THE REPOSITORY.

ALWAYS DO: When you feel work is complete, use the docker compose build readmebook to confirm you have no errors. If the build succeeds, then you can tell me it is ready to be tested.

---

1. Token-Efficient Documentation System

Why Token Efficiency Matters

Problem: Documentation consumes significant token budget, leaving limited context for implementation.

Solution: Documentation optimized for AI consumption, not human reading. Average 68-72% token reduction while preserving all technical details.

Documentation Structure

documentation/
├── TABLEOFCONTENTS.md          # Navigation index (read THIS FIRST)
├── README.md                    # Project overview
├── backend/
│   ├── database.md             # Schema, Prisma, migrations
│   └── services/
│       ├── auth.md             # Plex OAuth, JWT, RBAC
│       ├── config.md           # Settings, encryption
│       ├── jobs.md             # Bull queue, processors
│       └── scheduler.md        # Cron jobs, recurring tasks
├── integrations/
│   ├── plex.md                 # Library scanning, OAuth, matching
│   └── audible.md              # Web scraping, metadata
├── phase3/                     # Automation pipeline
│   ├── README.md               # Pipeline overview
│   ├── qbittorrent.md          # Download client
│   ├── prowlarr.md             # Indexer search
│   ├── ranking-algorithm.md    # Torrent selection
│   └── file-organization.md    # File management, seeding
├── frontend/
│   ├── components.md           # React components
│   ├── routing-auth.md         # Route protection
│   └── pages/
│       └── login.md            # Login page design
├── deployment/
│   └── docker.md               # Docker Compose, volumes
└── [feature-specific docs]

---

2. Using TABLEOFCONTENTS.md (MANDATORY)

RULE: Always Start Here

Before reading ANY documentation:

1. Read documentation/TABLEOFCONTENTS.md FIRST
2. Identify relevant sections for your task
3. Read ONLY the specific files you need
4. Never read all files sequentially (wastes tokens)

Example Workflow

Bad (Token wasteful):

Task: Fix Plex authentication
❌ Read README.md → backend/* → integrations/* → ...

Good (Token efficient):

Task: Fix Plex authentication
✅ Read TABLEOFCONTENTS.md → Identify: backend/services/auth.md, integrations/plex.md
✅ Read only those 2 files
✅ Begin implementation

TABLEOFCONTENTS.md Format

Maps questions/features to specific documentation files:

• "How does authentication work?" → backend/services/auth.md
• "How do downloads work?" → phase3/qbittorrent.md, backend/services/jobs.md
• Organized by: Authentication, Configuration, Database, Integrations, Automation, etc.

---

3. Token-Efficient Documentation Format

Mandatory Format Standards

All documentation MUST follow this token-optimized format:

Structure

# [Title]

**Status:** [✅ Implemented / ⏳ In Progress / ❌ Not Started] [Brief description]

## Overview
[1-2 sentence summary]

## Key Details
- Compact bullet lists (not prose)
- API endpoints with request/response
- Data models with field names/types
- Configuration keys
- Critical implementation notes

## API/Interfaces
[Tables or compact code blocks]

## Critical Issues (if any)
[Only important items]

## Related: [links to other docs]

Forbidden Content (Removed for Token Efficiency)

• ❌ Verbose prose explanations
• ❌ "Why?" sections (keep brief rationale only)
• ❌ Large ASCII diagrams (minimal only)
• ❌ Excessive examples (max 1-2)
• ❌ "Future Enhancements" sections
• ❌ "Testing Strategy" (unless critical)
• ❌ "Performance Considerations" (unless critical)
• ❌ Empty sections
• ❌ Decorative formatting

Required Content (Preserve Completely)

• ✅ API endpoint definitions
• ✅ Data model field names and types
• ✅ Configuration keys and values
• ✅ Status values and enums
• ✅ File paths and code locations
• ✅ Critical implementation details
• ✅ "Fixed Issues" (troubleshooting context)
• ✅ Essential code examples (1-2 max)

Format Examples

Before (Token wasteful - 180 lines):

# User Authentication Service

## Current State

**Status:** Implemented ✅

This service handles all authentication and authorization logic for the
ReadMeABook application, including Plex OAuth integration, JWT session
management, and role-based access control.

## Design Architecture

### Why Plex OAuth?

Plex OAuth was chosen for several important reasons:
- No need to manage passwords
- Users already have Plex accounts
- Seamless integration with Plex ecosystem
...
[continues for 150+ more lines]

After (Token efficient - 50 lines):

# User Authentication Service

**Status:** ✅ Implemented | Plex OAuth + JWT sessions + RBAC

## Overview
Handles Plex OAuth, JWT session management, role-based access control (user/admin).

## Key Details
- **Auth:** Plex OAuth flow → JWT tokens (access: 1h, refresh: 7d)
- **Roles:** user (requests only), admin (full access)
- **First user:** Auto-promoted to admin
- **Endpoints:**
  - POST /api/auth/plex/login → {authUrl, pinId}
  - GET /api/auth/plex/callback?pinId → {accessToken, refreshToken, user}
  - POST /api/auth/refresh → {accessToken}
  - GET /api/auth/me → {user}
- **Middleware:** requireAuth(), requireAdmin()
- **Storage:** HTTP-only cookies + localStorage

## JWT Payload
```json
{
  "sub": "user-uuid",
  "plexId": "plex-id",
  "role": "admin",
  "exp": 1234571490
}

---

4. Implementation Strategy

Step 1: Navigate with TABLEOFCONTENTS.md

• Read TABLEOFCONTENTS.md to find relevant docs
• Identify 1-3 specific files needed (not all docs)

Step 2: Read Minimal Context

• Read ONLY the identified files
• Focus on "Key Details" and "API/Interfaces" sections
• Skip examples unless implementing similar functionality

Step 3: Reiterate Understanding

• Brief paragraph (3-4 sentences max)
• What user wants, what's affected, expected outcome

Step 4: Create Implementation Plan (TodoWrite)

- [ ] Read: [specific doc files]
- [ ] Update: [specific doc files]
- [ ] Implement: [specific changes]
- [ ] Verify: [test steps]

Step 5: Implement

• Follow plan
• Update docs using token-efficient format
• Add file headers linking to docs

---

5. Documentation Maintenance

RULE: Update TABLEOFCONTENTS.md

When adding new documentation:

1. Create doc file using token-efficient format
2. Update TABLEOFCONTENTS.md with new mapping
3. Update parent README.md if needed

Example:

# Added new feature: Email notifications

Files created:
- documentation/backend/services/notifications.md

Updates required:
- ✅ Create notifications.md (token-efficient format)
- ✅ Add to TABLEOFCONTENTS.md: "Email notifications" → backend/services/notifications.md
- ✅ Update documentation/README.md → Backend section

RULE: Keep Docs Up-to-Date

• Before code changes: Read relevant docs
• After code changes: Update docs immediately
• Use token-efficient format for all updates

---

6. Code Standards

File Size Limits

• Max 300-400 lines per file
• Refactor if exceeding limit

Mandatory File Headers

/**
 * Component: User Authentication Service
 * Documentation: documentation/backend/services/auth.md
 */

Link Accuracy

• Header path MUST point to existing doc file
• Create doc BEFORE implementing code
• Use relative paths from project root

---

7. Token Budget Management

Critical Principle

Preserve tokens for implementation, not context gathering.

Token Budget Allocation:

• 20-30%: Reading relevant documentation (via TABLEOFCONTENTS.md)
• 70-80%: Implementation, problem-solving, code generation

Anti-Patterns (Token wasteful):

• ❌ Reading all documentation files
• ❌ Reading verbose examples when not needed
• ❌ Re-reading same docs multiple times
• ❌ Reading "Future Enhancements" sections

Best Practices (Token efficient):

• ✅ Use TABLEOFCONTENTS.md to target specific files
• ✅ Read only "Key Details" and "API/Interfaces" sections
• ✅ Skip examples unless implementing similar code
• ✅ Cache understanding in memory, don't re-read

---

8. Examples

Example 1: Bug Fix

Task: "Plex authentication fails with 403 error"

Process:

1. Read TABLEOFCONTENTS.md → Find: backend/services/auth.md, integrations/plex.md
2. Read only those 2 files (focus on API endpoints, error handling)
3. Identify issue: Token refresh logic
4. Fix code
5. Update backend/services/auth.md (token-efficient format)

Example 2: New Feature

Task: "Add email notifications for completed requests"

Process:

1. Read TABLEOFCONTENTS.md → Find: backend/services/scheduler.md, backend/services/jobs.md
2. Read those files for background job patterns
3. Create documentation/backend/services/notifications.md (token-efficient format)
4. Update TABLEOFCONTENTS.md: "Email notifications" → backend/services/notifications.md
5. Implement notification service
6. Add file header linking to notifications.md

---

9. Quality Checklist

Before completing any task:

• Used TABLEOFCONTENTS.md to find docs (not read all files)
• Read only necessary documentation
• Updated documentation in token-efficient format
• Updated TABLEOFCONTENTS.md if added new docs
• Added file headers to new code files
• No file exceeds 400 lines
• Documentation matches implementation

---

10. Summary

Key Points:

1. Always start with TABLEOFCONTENTS.md (navigation index)
2. Read only what you need (not all docs)
3. Use token-efficient format (bullets, tables, minimal prose)
4. Preserve tokens for implementation (not context gathering)
5. Update docs immediately (before/after code changes)
6. Update TABLEOFCONTENTS.md (when adding new docs)

Result:

• 68-72% token reduction in documentation
• Faster context gathering
• More tokens available for implementation
• Better AI performance on complex tasks

---

Remember: Documentation is for AI consumption. Token efficiency is critical. Always use TABLEOFCONTENTS.md.