flyer-crawler.projectium.com/docs/AI-DOCUMENTATION-INDEX.md

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	API Response Patterns, Input Validation
Add repository method	CODE-PATTERNS.md	Repository Patterns (get*/find*/list*)
Fix failing test	TESTING.md	Known Integration Test Issues
Run tests correctly	TESTING.md	Test Execution Environment
Add database column	DATABASE-GUIDE.md	Schema sync required
Deploy to production	DEPLOYMENT.md	Application Deployment
Debug container issue	DEBUGGING.md	Container Issues
Configure environment	ENVIRONMENT.md	Configuration by Environment
Add background job	CODE-PATTERNS.md	Background Jobs
Handle errors correctly	CODE-PATTERNS.md	Error Handling
Use transactions	CODE-PATTERNS.md	Transaction Management
Add authentication	AUTHENTICATION.md	JWT Token Architecture
Cache data	CODE-PATTERNS.md	Caching
Check PM2 status	DEV-CONTAINER.md	PM2 Process Management
View logs	DEBUGGING.md	PM2 Log Access
Understand architecture	OVERVIEW.md	System Architecture Diagram
Check ADR for decision	adr/index.md	ADR by category
Use subagent	subagents/OVERVIEW.md	Available Subagents
API versioning	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, CLAUDE.md schema sync section
Migration needed	DATABASE.md, ADR-013, ADR-023
Query performance	DEBUGGING.md Query Performance Issues
Connection errors	DEBUGGING.md Database Issues
Transaction patterns	CODE-PATTERNS.md Transaction Management, ADR-002
Repository methods	CODE-PATTERNS.md Repository Patterns, ADR-034

Test Failures

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

Deployment Issues

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

Frontend/UI Changes

Problem	Documents
Component patterns	FRONTEND-GUIDE.md, ADR-044
Design tokens	DESIGN_TOKENS.md, ADR-012
State management	ADR-005, OVERVIEW.md Frontend Stack
Hot reload broken	DEBUGGING.md Frontend Issues
CORS errors	DEBUGGING.md API Calls Failing

API Development

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

Background Jobs

Problem	Documents
Jobs not processing	DEBUGGING.md Background Job Issues
Queue configuration	CODE-PATTERNS.md Background Jobs, ADR-006
Worker crashes	DEBUGGING.md, ADR-053
Scheduled jobs	ADR-037, OVERVIEW.md Scheduled Jobs

---

Document Priority Matrix

CRITICAL (Read First)

Document	Purpose	Key Content
CLAUDE.md	AI agent instructions	Rules, patterns, known issues
ADR-014	Platform requirement	Tests MUST run in container
DEV-CONTAINER.md	Development environment	PM2, Logstash, services

HIGH (Core Development)

Document	Purpose	Key Content
CODE-PATTERNS.md	Code templates	Error handling, repos, APIs
TESTING.md	Test execution	Commands, known issues
DATABASE.md	Schema reference	Setup, extensions, users
ADR-034	Repository naming	get*/find*/list*
ADR-028	API responses	sendSuccess/sendError
ADR-001	Error handling	handleDbError, NotFoundError

MEDIUM (Specialized Tasks)

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

LOW (Reference/Historical)

Document	Purpose	Key Content
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
Database changes	db-dev	DATABASE-GUIDE.md
Create tests	testwriter	TESTER-GUIDE.md
Fix failing tests	tester	TESTER-GUIDE.md
Container/deployment	devops	DEVOPS-GUIDE.md
UI components	frontend-specialist	FRONTEND-GUIDE.md
External APIs	integrations-specialist	-
Security review	security-engineer	SECURITY-DEBUG-GUIDE.md
Production errors	log-debug	SECURITY-DEBUG-GUIDE.md
AI/Gemini issues	ai-usage	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

# 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