commit a3ba192fbdeec5812707729db29ae089d30af28c Author: kikootwo Date: Wed Jan 28 11:41:24 2026 -0500 Initial commit diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..62facc3 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,66 @@ +# Dependencies +node_modules +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Generated Prisma client (will be regenerated in container) +src/generated + +# Testing +coverage +.nyc_output + +# Next.js +.next +out + +# Production +build +dist + +# Misc +.DS_Store +*.pem + +# Debug +*.log +logs + +# Local env files +.env +.env.local +.env.development.local +.env.test.local +.env.production.local + +# IDEs +.vscode +.idea +*.swp +*.swo +*~ + +# Git +.git +.gitignore +.gitattributes + +# CI/CD +.github + +# Documentation (not needed in runtime) +*.md +!README.md + +# Docker +Dockerfile +docker-compose.yml +.dockerignore + +# Data directories (will be mounted as volumes) +config +downloads +media +pgdata +redisdata diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..4f4726f --- /dev/null +++ b/.env.example @@ -0,0 +1,25 @@ +# Database +DATABASE_URL="postgresql://user:password@localhost:5432/readmeabook?schema=public" + +# Redis +REDIS_URL="redis://localhost:6379" + +# JWT +JWT_SECRET="change-this-to-a-random-secret-key" +JWT_REFRESH_SECRET="change-this-to-another-random-secret-key" + +# Encryption +CONFIG_ENCRYPTION_KEY="change-this-to-a-32-character-key" + +# Plex OAuth +PLEX_CLIENT_IDENTIFIER="readmeabook-unique-client-id" +PLEX_PRODUCT_NAME="ReadMeABook" +PLEX_OAUTH_CALLBACK_URL="http://localhost:3030/api/auth/plex/callback" + +# Paths (for local development) +DOWNLOADS_PATH="/downloads" +MEDIA_PATH="/media" + +# Application +NODE_ENV="development" +PORT="3030" diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..6675a31 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +# Auto detect text files and perform LF normalization +* text=auto + +# Force LF line endings for shell scripts (critical for Docker) +*.sh text eol=lf diff --git a/.github/workflows/build-unified-image.yml b/.github/workflows/build-unified-image.yml new file mode 100644 index 0000000..1c20734 --- /dev/null +++ b/.github/workflows/build-unified-image.yml @@ -0,0 +1,87 @@ +name: Build and Publish Unified Docker Image + +on: + push: + branches: + - main + tags: + - 'v*' + workflow_dispatch: + +env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }} + +jobs: + build-and-push: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to GitHub Container Registry + if: github.event_name != 'pull_request' + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract metadata (tags, labels) + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=semver,pattern={{major}} + type=sha,prefix=sha- + type=raw,value=latest,enable={{is_default_branch}} + labels: | + org.opencontainers.image.title=ReadMeABook Unified + org.opencontainers.image.description=All-in-one audiobook request and automation system (PostgreSQL + Redis + App) + org.opencontainers.image.vendor=ReadMeABook + + - name: Build and push unified Docker image + uses: docker/build-push-action@v5 + with: + context: . + file: ./dockerfile.unified + platforms: linux/amd64,linux/arm64 + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max + + - name: Generate deployment instructions + if: github.event_name != 'pull_request' + run: | + echo "## 🎉 Docker image published successfully!" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### 📦 Available tags:" >> $GITHUB_STEP_SUMMARY + echo '```' >> $GITHUB_STEP_SUMMARY + echo "${{ steps.meta.outputs.tags }}" >> $GITHUB_STEP_SUMMARY + echo '```' >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### 🚀 Quick start:" >> $GITHUB_STEP_SUMMARY + echo '```bash' >> $GITHUB_STEP_SUMMARY + echo "docker run -d \\" >> $GITHUB_STEP_SUMMARY + echo " --name readmeabook \\" >> $GITHUB_STEP_SUMMARY + echo " -p 3030:3030 \\" >> $GITHUB_STEP_SUMMARY + echo " -v ./config:/app/config \\" >> $GITHUB_STEP_SUMMARY + echo " -v ./downloads:/downloads \\" >> $GITHUB_STEP_SUMMARY + echo " -v ./media:/media \\" >> $GITHUB_STEP_SUMMARY + echo " -v readmeabook-data:/var/lib/postgresql/data \\" >> $GITHUB_STEP_SUMMARY + echo " ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest" >> $GITHUB_STEP_SUMMARY + echo '```' >> $GITHUB_STEP_SUMMARY diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..03427a2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,51 @@ +# IDE +.idea + +# Dependencies +/node_modules +/.pnp +.pnp.* +.yarn/* +!.yarn/patches +!.yarn/plugins +!.yarn/releases +!.yarn/versions + +# Testing +/coverage + +# Next.js +/.next/ +/out/ + +# Production +/build + +# Misc +.DS_Store +*.pem + +# Debug +npm-debug.log* +yarn-debug.log* +yarn-error.log* +.pnpm-debug.log* + +# Environment files +.env* +!.env.example + +# Vercel +.vercel + +# TypeScript +*.tsbuildinfo +next-env.d.ts + +# Local data (Docker volumes) +/config +/downloads +/media + +/src/generated/prisma +/RMAB \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e6ddeca --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,357 @@ +# AGENTS.md - Project Standards & Workflow + +**Critical:** This document defines AI-optimized documentation standards and development workflow. + +--- + +## 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 +```markdown +# [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):** +```markdown +# 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):** +```markdown +# 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:** +```markdown +# 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 +```typescript +/** + * 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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..214688e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,357 @@ +# CLAUDE.md - Project Standards & Workflow + +**Critical:** This document defines AI-optimized documentation standards and development workflow. + +--- + +## 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 +```markdown +# [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):** +```markdown +# 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):** +```markdown +# 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:** +```markdown +# 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 +```typescript +/** + * 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..edf845d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,321 @@ +# Contributing to ReadMeABook + +Thank you for your interest in contributing to ReadMeABook! This document provides guidelines and instructions for contributing to the project. + +--- + +## 🤝 How to Contribute + +### Reporting Issues + +If you encounter a bug or have a feature request: + +1. **Check existing issues** - Search [GitHub Issues](https://github.com/kikootwo/ReadMeABook/issues) to see if it's already reported +2. **Create a new issue** - Use the appropriate issue template +3. **Provide details** - Include: + - Clear description of the problem/feature + - Steps to reproduce (for bugs) + - Expected vs actual behavior + - Environment details (OS, Docker version, etc.) + - Relevant logs or screenshots + +### Submitting Pull Requests + +1. **Fork the repository** +2. **Create a feature branch** from `main`: + ```bash + git checkout -b feature/your-feature-name + ``` +3. **Make your changes** following our coding standards +4. **Test your changes** thoroughly +5. **Commit with clear messages**: + ```bash + git commit -m "Add: brief description of changes" + ``` +6. **Push to your fork**: + ```bash + git push origin feature/your-feature-name + ``` +7. **Open a Pull Request** with: + - Clear title and description + - Reference to related issues + - Screenshots/demos if applicable + +--- + +## 🏗️ Development Setup + +### Prerequisites + +- Node.js 20+ +- Docker & Docker Compose +- Git + +### Local Development + +1. **Clone the repository:** + ```bash + git clone https://github.com/kikootwo/ReadMeABook.git + cd ReadMeABook + ``` + +2. **Install dependencies:** + ```bash + npm install + ``` + +3. **Set up environment:** + ```bash + cp .env.example .env + # Edit .env with your local configuration + ``` + +4. **Start development stack:** + ```bash + # Using Docker Compose (recommended) + docker compose -f docker-compose.local.yml up -d + + # Or run services separately + docker compose -f docker-compose.debug.yml up -d postgres redis + npm run dev + ``` + +5. **Run database migrations:** + ```bash + npm run prisma:generate + npm run db:push + ``` + +6. **Access the app:** + - App: http://localhost:3030 + - Prisma Studio: `npm run prisma:studio` + +--- + +## 📝 Coding Standards + +### General Guidelines + +- **Follow existing code style** - Use the project's ESLint configuration +- **Write clear, descriptive variable names** +- **Add comments for complex logic** +- **Keep functions small and focused** +- **Test your changes** + +### TypeScript + +- Use TypeScript for all new code +- Define proper types (avoid `any`) +- Use interfaces for object shapes +- Export types when they're reusable + +### React Components + +- Use functional components with hooks +- Keep components focused and reusable +- Use proper TypeScript props typing +- Follow the existing component structure in `src/components/` + +### File Organization + +- **Max 300-400 lines per file** - Refactor if larger +- **Add file headers** to reference documentation: + ```typescript + /** + * Component: Feature Name + * Documentation: documentation/path/to/doc.md + */ + ``` + +### Database Changes + +- Always use Prisma migrations +- Test migrations with seed data +- Document schema changes in pull request + +--- + +## 📚 Documentation + +### Updating Documentation + +When making changes that affect documentation: + +1. **Update relevant docs** in `documentation/` +2. **Use token-efficient format** (see [CLAUDE.md](CLAUDE.md)) +3. **Update TABLEOFCONTENTS.md** if adding new docs +4. **Keep docs in sync** with code changes + +### Documentation Standards + +- Use bullet points over prose +- Include code examples where helpful +- Keep status indicators updated (✅/⏳/❌) +- Link to related documentation + +--- + +## 🧪 Testing + +### Before Submitting + +- Test locally with Docker Compose +- Verify no console errors +- Test with clean database (migrations) +- Check responsive design (if UI changes) +- Verify all features still work + +### Manual Testing Checklist + +- [ ] Login with Plex works +- [ ] Library scan completes +- [ ] Book requests can be created +- [ ] Settings can be updated +- [ ] Background jobs run correctly + +--- + +## 🔍 Code Review Process + +### What We Look For + +- **Functionality** - Does it work as intended? +- **Code quality** - Is it clean and maintainable? +- **Testing** - Has it been adequately tested? +- **Documentation** - Are docs updated? +- **Breaking changes** - Are they necessary and documented? + +### Review Timeline + +- Initial review: Within 1-2 weeks +- Follow-up on feedback: Ongoing +- Merge: When approved and CI passes + +--- + +## 🚀 Release Process + +### Versioning + +We follow [Semantic Versioning](https://semver.org/): + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +### Release Cycle + +- Releases are tagged as needed +- Docker images automatically built on push to `main` +- Breaking changes documented in release notes + +--- + +## 💡 Development Tips + +### Working with Prisma + +```bash +# Generate Prisma client after schema changes +npm run prisma:generate + +# Push schema changes to database +npm run db:push + +# Open Prisma Studio +npm run prisma:studio +``` + +### Working with Docker + +```bash +# Build local image +docker compose -f docker-compose.local.yml build + +# View logs +docker compose -f docker-compose.local.yml logs -f + +# Reset database +docker compose -f docker-compose.local.yml down -v +``` + +### Debugging + +- Use `LOG_LEVEL=debug` in environment +- Check browser console for frontend issues +- Use Prisma Studio to inspect database +- Check Docker logs for backend issues + +--- + +## 📋 Commit Message Guidelines + +### Format + +``` +: + + + +