# AI Documentation Index

Machine-optimized navigation for AI agents. Structured for vector retrieval and semantic search.

---

## Quick Lookup Table

| Task/Question           | Primary Doc                                         | Section/ADR                             |
| ----------------------- | --------------------------------------------------- | --------------------------------------- |
| Add new API endpoint    | [CODE-PATTERNS.md](development/CODE-PATTERNS.md)    | API Response Patterns, Input Validation |
| Add repository method   | [CODE-PATTERNS.md](development/CODE-PATTERNS.md)    | Repository Patterns (get*/find*/list\*) |
| Fix failing test        | [TESTING.md](development/TESTING.md)                | Known Integration Test Issues           |
| Run tests correctly     | [TESTING.md](development/TESTING.md)                | Test Execution Environment              |
| Add database column     | [DATABASE-GUIDE.md](subagents/DATABASE-GUIDE.md)    | Schema sync required                    |
| Deploy to production    | [DEPLOYMENT.md](operations/DEPLOYMENT.md)           | Application Deployment                  |
| Debug container issue   | [DEBUGGING.md](development/DEBUGGING.md)            | Container Issues                        |
| Configure environment   | [ENVIRONMENT.md](getting-started/ENVIRONMENT.md)    | Configuration by Environment            |
| Add background job      | [CODE-PATTERNS.md](development/CODE-PATTERNS.md)    | Background Jobs                         |
| Handle errors correctly | [CODE-PATTERNS.md](development/CODE-PATTERNS.md)    | Error Handling                          |
| Use transactions        | [CODE-PATTERNS.md](development/CODE-PATTERNS.md)    | Transaction Management                  |
| Add authentication      | [AUTHENTICATION.md](architecture/AUTHENTICATION.md) | JWT Token Architecture                  |
| Cache data              | [CODE-PATTERNS.md](development/CODE-PATTERNS.md)    | Caching                                 |
| Check PM2 status        | [DEV-CONTAINER.md](development/DEV-CONTAINER.md)    | PM2 Process Management                  |
| View logs               | [DEBUGGING.md](development/DEBUGGING.md)            | PM2 Log Access                          |
| Understand architecture | [OVERVIEW.md](architecture/OVERVIEW.md)             | System Architecture Diagram             |
| Check ADR for decision  | [adr/index.md](adr/index.md)                        | ADR by category                         |
| Use subagent            | [subagents/OVERVIEW.md](subagents/OVERVIEW.md)      | Available Subagents                     |
| API versioning          | [API-VERSIONING.md](development/API-VERSIONING.md)  | Phase 2 infrastructure                  |

---

## Documentation Tree

```
docs/
+-- AI-DOCUMENTATION-INDEX.md      # THIS FILE - AI navigation index
+-- README.md                      # Human-readable doc hub
|
+-- adr/                           # Architecture Decision Records (57 ADRs)
|   +-- index.md                   # ADR index by category
|   +-- 0001-*.md                  # Standardized error handling
|   +-- 0002-*.md                  # Transaction management (withTransaction)
|   +-- 0003-*.md                  # Input validation (Zod middleware)
|   +-- 0008-*.md                  # API versioning (/api/v1/)
|   +-- 0014-*.md                  # Platform: Linux only (CRITICAL)
|   +-- 0028-*.md                  # API response (sendSuccess/sendError)
|   +-- 0034-*.md                  # Repository pattern (get*/find*/list*)
|   +-- 0035-*.md                  # Service layer architecture
|   +-- 0050-*.md                  # PostgreSQL observability + Logstash
|   +-- 0057-*.md                  # Test remediation post-API versioning
|   +-- adr-implementation-tracker.md  # Implementation status
|
+-- architecture/
|   +-- OVERVIEW.md                # System architecture, data flows, entities
|   +-- DATABASE.md                # Schema design, extensions, setup
|   +-- AUTHENTICATION.md          # OAuth, JWT, security features
|   +-- WEBSOCKET_USAGE.md         # Real-time communication patterns
|   +-- api-versioning-infrastructure.md  # Phase 2 versioning details
|
+-- development/
|   +-- CODE-PATTERNS.md           # Error handling, repos, API responses
|   +-- TESTING.md                 # Unit/integration/E2E, known issues
|   +-- DEBUGGING.md               # Container, DB, API, PM2 debugging
|   +-- DEV-CONTAINER.md           # PM2, Logstash, container services
|   +-- API-VERSIONING.md          # API versioning workflows
|   +-- DESIGN_TOKENS.md           # Neo-Brutalism design system
|   +-- ERROR-LOGGING-PATHS.md     # req.originalUrl pattern
|   +-- test-path-migration.md     # Test file reorganization
|
+-- getting-started/
|   +-- QUICKSTART.md              # Quick setup instructions
|   +-- INSTALL.md                 # Full installation guide
|   +-- ENVIRONMENT.md             # Environment variables reference
|
+-- operations/
|   +-- DEPLOYMENT.md              # Production deployment guide
|   +-- BARE-METAL-SETUP.md        # Server provisioning
|   +-- MONITORING.md              # Bugsink, health checks
|   +-- LOGSTASH-QUICK-REF.md      # Log aggregation reference
|   +-- LOGSTASH-TROUBLESHOOTING.md  # Logstash debugging
|
+-- subagents/
|   +-- OVERVIEW.md                # Subagent system introduction
|   +-- CODER-GUIDE.md             # Code development patterns
|   +-- TESTER-GUIDE.md            # Testing strategies
|   +-- DATABASE-GUIDE.md          # Database workflows
|   +-- DEVOPS-GUIDE.md            # Deployment/infrastructure
|   +-- FRONTEND-GUIDE.md          # UI/UX development
|   +-- AI-USAGE-GUIDE.md          # Gemini integration
|   +-- DOCUMENTATION-GUIDE.md     # Writing docs
|   +-- SECURITY-DEBUG-GUIDE.md    # Security and debugging
|
+-- tools/
|   +-- MCP-CONFIGURATION.md       # MCP servers setup
|   +-- BUGSINK-SETUP.md           # Error tracking setup
|   +-- VSCODE-SETUP.md            # Editor configuration
|
+-- archive/                       # Historical docs, session notes
    +-- sessions/                  # Development session logs
    +-- plans/                     # Feature implementation plans
    +-- research/                  # Investigation notes
```

---

## Problem-to-Document Mapping

### Database Issues

| Problem              | Documents                                                                                       |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| Schema out of sync   | [DATABASE-GUIDE.md](subagents/DATABASE-GUIDE.md), [CLAUDE.md](../CLAUDE.md) schema sync section |
| Migration needed     | [DATABASE.md](architecture/DATABASE.md), ADR-013, ADR-023                                       |
| Query performance    | [DEBUGGING.md](development/DEBUGGING.md) Query Performance Issues                               |
| Connection errors    | [DEBUGGING.md](development/DEBUGGING.md) Database Issues                                        |
| Transaction patterns | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) Transaction Management, ADR-002                |
| Repository methods   | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) Repository Patterns, ADR-034                   |

### Test Failures

| Problem                      | Documents                                                             |
| ---------------------------- | --------------------------------------------------------------------- |
| Tests fail in container      | [TESTING.md](development/TESTING.md), ADR-014                         |
| Vitest globalSetup isolation | [CLAUDE.md](../CLAUDE.md) Integration Test Issues #1                  |
| Cache stale after insert     | [CLAUDE.md](../CLAUDE.md) Integration Test Issues #3                  |
| Queue interference           | [CLAUDE.md](../CLAUDE.md) Integration Test Issues #2                  |
| API path mismatches          | [TESTING.md](development/TESTING.md) API Versioning in Tests, ADR-057 |
| Type check failures          | [DEBUGGING.md](development/DEBUGGING.md) Type Check Failures          |
| TZ environment breaks async  | [CLAUDE.md](../CLAUDE.md) Integration Test Issues #7                  |

### Deployment Issues

| Problem               | Documents                                                                             |
| --------------------- | ------------------------------------------------------------------------------------- |
| PM2 not starting      | [DEBUGGING.md](development/DEBUGGING.md) PM2 Process Issues                           |
| NGINX configuration   | [DEPLOYMENT.md](operations/DEPLOYMENT.md) NGINX Configuration                         |
| SSL certificates      | [DEBUGGING.md](development/DEBUGGING.md) SSL Certificate Issues                       |
| CI/CD failures        | [DEPLOYMENT.md](operations/DEPLOYMENT.md) CI/CD Pipeline, ADR-017                     |
| Container won't start | [DEBUGGING.md](development/DEBUGGING.md) Container Issues                             |
| Bugsink not receiving | [BUGSINK-SETUP.md](tools/BUGSINK-SETUP.md), [MONITORING.md](operations/MONITORING.md) |

### Frontend/UI Changes

| Problem            | Documents                                                       |
| ------------------ | --------------------------------------------------------------- |
| Component patterns | [FRONTEND-GUIDE.md](subagents/FRONTEND-GUIDE.md), ADR-044       |
| Design tokens      | [DESIGN_TOKENS.md](development/DESIGN_TOKENS.md), ADR-012       |
| State management   | ADR-005, [OVERVIEW.md](architecture/OVERVIEW.md) Frontend Stack |
| Hot reload broken  | [DEBUGGING.md](development/DEBUGGING.md) Frontend Issues        |
| CORS errors        | [DEBUGGING.md](development/DEBUGGING.md) API Calls Failing      |

### API Development

| Problem          | Documents                                                                       |
| ---------------- | ------------------------------------------------------------------------------- |
| Response format  | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) API Response Patterns, ADR-028 |
| Input validation | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) Input Validation, ADR-003      |
| Error handling   | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) Error Handling, ADR-001        |
| Rate limiting    | ADR-032, [OVERVIEW.md](architecture/OVERVIEW.md)                                |
| API versioning   | [API-VERSIONING.md](development/API-VERSIONING.md), ADR-008                     |
| Authentication   | [AUTHENTICATION.md](architecture/AUTHENTICATION.md), ADR-048                    |

### Background Jobs

| Problem             | Documents                                                                 |
| ------------------- | ------------------------------------------------------------------------- |
| Jobs not processing | [DEBUGGING.md](development/DEBUGGING.md) Background Job Issues            |
| Queue configuration | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) Background Jobs, ADR-006 |
| Worker crashes      | [DEBUGGING.md](development/DEBUGGING.md), ADR-053                         |
| Scheduled jobs      | ADR-037, [OVERVIEW.md](architecture/OVERVIEW.md) Scheduled Jobs           |

---

## Document Priority Matrix

### CRITICAL (Read First)

| Document                                                        | Purpose                 | Key Content                   |
| --------------------------------------------------------------- | ----------------------- | ----------------------------- |
| [CLAUDE.md](../CLAUDE.md)                                       | AI agent instructions   | Rules, patterns, known issues |
| [ADR-014](adr/0014-containerization-and-deployment-strategy.md) | Platform requirement    | Tests MUST run in container   |
| [DEV-CONTAINER.md](development/DEV-CONTAINER.md)                | Development environment | PM2, Logstash, services       |

### HIGH (Core Development)

| Document                                            | Purpose           | Key Content                  |
| --------------------------------------------------- | ----------------- | ---------------------------- |
| [CODE-PATTERNS.md](development/CODE-PATTERNS.md)    | Code templates    | Error handling, repos, APIs  |
| [TESTING.md](development/TESTING.md)                | Test execution    | Commands, known issues       |
| [DATABASE.md](architecture/DATABASE.md)             | Schema reference  | Setup, extensions, users     |
| [ADR-034](adr/0034-repository-pattern-standards.md) | Repository naming | get*/find*/list\*            |
| [ADR-028](adr/0028-api-response-standardization.md) | API responses     | sendSuccess/sendError        |
| [ADR-001](adr/0001-standardized-error-handling.md)  | Error handling    | handleDbError, NotFoundError |

### MEDIUM (Specialized Tasks)

| Document                                            | Purpose               | Key Content              |
| --------------------------------------------------- | --------------------- | ------------------------ |
| [subagents/OVERVIEW.md](subagents/OVERVIEW.md)      | Subagent selection    | When to delegate         |
| [DEPLOYMENT.md](operations/DEPLOYMENT.md)           | Production deployment | PM2, NGINX, CI/CD        |
| [DEBUGGING.md](development/DEBUGGING.md)            | Troubleshooting       | Common issues, solutions |
| [ENVIRONMENT.md](getting-started/ENVIRONMENT.md)    | Config reference      | Variables by environment |
| [AUTHENTICATION.md](architecture/AUTHENTICATION.md) | Auth patterns         | OAuth, JWT, security     |
| [API-VERSIONING.md](development/API-VERSIONING.md)  | Versioning            | /api/v1/ prefix          |

### LOW (Reference/Historical)

| Document             | Purpose            | Key Content               |
| -------------------- | ------------------ | ------------------------- |
| [archive/](archive/) | Historical docs    | Session notes, old plans  |
| ADR-013, ADR-023     | Migration strategy | Proposed, not implemented |
| ADR-024              | Feature flags      | Proposed                  |
| ADR-025              | i18n/l10n          | Proposed                  |

---

## Cross-Reference Matrix

| Document             | References                                                                      | Referenced By                                          |
| -------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **CLAUDE.md**        | ADR-001, ADR-002, ADR-008, ADR-014, ADR-028, ADR-034, ADR-035, ADR-050, ADR-057 | All development docs                                   |
| **ADR-008**          | ADR-028                                                                         | API-VERSIONING.md, TESTING.md, ADR-057                 |
| **ADR-014**          | -                                                                               | CLAUDE.md, TESTING.md, DEPLOYMENT.md, DEV-CONTAINER.md |
| **ADR-028**          | ADR-001                                                                         | CODE-PATTERNS.md, OVERVIEW.md                          |
| **ADR-034**          | ADR-001                                                                         | CODE-PATTERNS.md, DATABASE-GUIDE.md                    |
| **ADR-057**          | ADR-008, ADR-028                                                                | TESTING.md                                             |
| **CODE-PATTERNS.md** | ADR-001, ADR-002, ADR-003, ADR-028, ADR-034, ADR-036, ADR-048                   | CODER-GUIDE.md                                         |
| **TESTING.md**       | ADR-014, ADR-057, CLAUDE.md                                                     | TESTER-GUIDE.md, DEBUGGING.md                          |
| **DEBUGGING.md**     | DEV-CONTAINER.md, TESTING.md, MONITORING.md                                     | DEVOPS-GUIDE.md                                        |
| **DEV-CONTAINER.md** | ADR-014, ADR-050, ecosystem.dev.config.cjs                                      | DEBUGGING.md, CLAUDE.md                                |
| **OVERVIEW.md**      | ADR-001 through ADR-050+                                                        | All architecture docs                                  |
| **DATABASE.md**      | ADR-002, ADR-013, ADR-055                                                       | DATABASE-GUIDE.md                                      |

---

## Navigation Patterns

### Adding a Feature

```
1. CLAUDE.md              -> Project rules, patterns
2. CODE-PATTERNS.md       -> Implementation templates
3. Relevant subagent guide -> Domain-specific patterns
4. Related ADRs           -> Design decisions
5. TESTING.md             -> Test requirements
```

### Fixing a Bug

```
1. DEBUGGING.md           -> Common issues checklist
2. TESTING.md             -> Run tests in container
3. Error logs (pm2/bugsink) -> Identify root cause
4. CODE-PATTERNS.md       -> Correct pattern reference
5. Related ADR            -> Architectural context
```

### Deploying

```
1. DEPLOYMENT.md          -> Deployment procedures
2. ENVIRONMENT.md         -> Required variables
3. MONITORING.md          -> Health check verification
4. LOGSTASH-QUICK-REF.md  -> Log aggregation check
```

### Database Changes

```
1. DATABASE-GUIDE.md      -> Schema sync requirements (CRITICAL)
2. DATABASE.md            -> Schema design patterns
3. ADR-002                -> Transaction patterns
4. ADR-034                -> Repository methods
5. ADR-055                -> Normalization rules
```

### Subagent Selection

| Task Type             | Subagent                  | Guide                                                        |
| --------------------- | ------------------------- | ------------------------------------------------------------ |
| Write production code | `coder`                   | [CODER-GUIDE.md](subagents/CODER-GUIDE.md)                   |
| Database changes      | `db-dev`                  | [DATABASE-GUIDE.md](subagents/DATABASE-GUIDE.md)             |
| Create tests          | `testwriter`              | [TESTER-GUIDE.md](subagents/TESTER-GUIDE.md)                 |
| Fix failing tests     | `tester`                  | [TESTER-GUIDE.md](subagents/TESTER-GUIDE.md)                 |
| Container/deployment  | `devops`                  | [DEVOPS-GUIDE.md](subagents/DEVOPS-GUIDE.md)                 |
| UI components         | `frontend-specialist`     | [FRONTEND-GUIDE.md](subagents/FRONTEND-GUIDE.md)             |
| External APIs         | `integrations-specialist` | -                                                            |
| Security review       | `security-engineer`       | [SECURITY-DEBUG-GUIDE.md](subagents/SECURITY-DEBUG-GUIDE.md) |
| Production errors     | `log-debug`               | [SECURITY-DEBUG-GUIDE.md](subagents/SECURITY-DEBUG-GUIDE.md) |
| AI/Gemini issues      | `ai-usage`                | [AI-USAGE-GUIDE.md](subagents/AI-USAGE-GUIDE.md)             |

---

## Key File Quick Reference

### Configuration

| File                       | Purpose                      |
| -------------------------- | ---------------------------- |
| `server.ts`                | Express app setup            |
| `src/config/env.ts`        | Environment validation (Zod) |
| `ecosystem.dev.config.cjs` | PM2 dev config               |
| `ecosystem.config.cjs`     | PM2 prod config              |
| `vite.config.ts`           | Vite build config            |

### Core Implementation

| File                                | Purpose                             |
| ----------------------------------- | ----------------------------------- |
| `src/routes/*.routes.ts`            | API route handlers                  |
| `src/services/db/*.db.ts`           | Repository layer                    |
| `src/services/*.server.ts`          | Server-only services                |
| `src/services/queues.server.ts`     | BullMQ queue definitions            |
| `src/services/workers.server.ts`    | BullMQ workers                      |
| `src/utils/apiResponse.ts`          | sendSuccess/sendError/sendPaginated |
| `src/services/db/errors.db.ts`      | handleDbError, NotFoundError        |
| `src/services/db/transaction.db.ts` | withTransaction                     |

### Database Schema

| File                           | Purpose                             |
| ------------------------------ | ----------------------------------- |
| `sql/master_schema_rollup.sql` | Test DB, complete reference         |
| `sql/initial_schema.sql`       | Fresh install (identical to rollup) |
| `sql/migrations/*.sql`         | Production ALTER statements         |

### Testing

| File                               | Purpose                 |
| ---------------------------------- | ----------------------- |
| `vitest.config.ts`                 | Unit test config        |
| `vitest.config.integration.ts`     | Integration test config |
| `vitest.config.e2e.ts`             | E2E test config         |
| `src/tests/utils/mockFactories.ts` | Mock data factories     |
| `src/tests/utils/storeHelpers.ts`  | Store test helpers      |

---

## ADR Quick Reference

### By Implementation Status

**Implemented**: 001, 002, 003, 004, 006, 008, 009, 010, 016, 017, 020, 021, 028, 032, 033, 034, 035, 036, 037, 038, 040, 041, 043, 044, 045, 046, 050, 051, 052, 055, 057

**Partially Implemented**: 012, 014, 015, 048

**Proposed**: 011, 013, 022, 023, 024, 025, 029, 030, 031, 039, 047, 053, 054, 056

### By Category

| Category              | ADRs                                        |
| --------------------- | ------------------------------------------- |
| Core Infrastructure   | 002, 007, 020, 030                          |
| Data Management       | 009, 013, 019, 023, 031, 055                |
| API & Integration     | 003, 008, 018, 022, 028                     |
| Security              | 001, 011, 016, 029, 032, 033, 048           |
| Observability         | 004, 015, 050, 051, 052, 056                |
| Deployment & Ops      | 006, 014, 017, 024, 037, 038, 053, 054      |
| Frontend/UI           | 005, 012, 025, 026, 044                     |
| Dev Workflow          | 010, 021, 027, 040, 045, 047, 057           |
| Architecture Patterns | 034, 035, 036, 039, 041, 042, 043, 046, 049 |

---

## Essential Commands

```bash
# Run all tests (MUST use container)
podman exec -it flyer-crawler-dev npm test

# Run unit tests
podman exec -it flyer-crawler-dev npm run test:unit

# Run type check
podman exec -it flyer-crawler-dev npm run type-check

# Run integration tests
podman exec -it flyer-crawler-dev npm run test:integration

# PM2 status
podman exec -it flyer-crawler-dev pm2 status

# PM2 logs
podman exec -it flyer-crawler-dev pm2 logs

# Restart all processes
podman exec -it flyer-crawler-dev pm2 restart all
```

---

_This index is optimized for AI agent consumption. Updated: 2026-01-28_