# Flyer Crawler Documentation

Welcome to the Flyer Crawler documentation. This guide will help you navigate the various documentation resources available.

## Quick Links

- [Main README](../README.md) - Project overview and quick start
- [CLAUDE.md](../CLAUDE.md) - AI agent instructions and project guidelines
- [CONTRIBUTING.md](../CONTRIBUTING.md) - Development workflow and contribution guide

## Documentation Structure

### 🚀 Getting Started

New to the project? Start here:

- [Installation Guide](getting-started/INSTALL.md) - Complete setup instructions
- [Environment Configuration](getting-started/ENVIRONMENT.md) - Environment variables and secrets

### 🏗️ Architecture

Understand how the system works:

- [System Overview](architecture/OVERVIEW.md) - High-level architecture
- [Database Schema](architecture/DATABASE.md) - Database design and entities
- [Authentication](architecture/AUTHENTICATION.md) - OAuth and JWT authentication
- [WebSocket Usage](architecture/WEBSOCKET_USAGE.md) - Real-time communication patterns

### 💻 Development

Day-to-day development guides:

- [Testing Guide](development/TESTING.md) - Unit, integration, and E2E testing
- [Code Patterns](development/CODE-PATTERNS.md) - Common code patterns and ADR examples
- [API Versioning](development/API-VERSIONING.md) - API versioning infrastructure and workflows
- [Design Tokens](development/DESIGN_TOKENS.md) - UI design system and Neo-Brutalism
- [Debugging Guide](development/DEBUGGING.md) - Common debugging patterns
- [Dev Container](development/DEV-CONTAINER.md) - Development container setup and PM2

### 🔧 Operations

Production operations and deployment:

- [Deployment Guide](operations/DEPLOYMENT.md) - Deployment procedures
- [Bare Metal Setup](operations/BARE-METAL-SETUP.md) - Server provisioning
- [Logstash Quick Reference](operations/LOGSTASH-QUICK-REF.md) - Log aggregation
- [Logstash Troubleshooting](operations/LOGSTASH-TROUBLESHOOTING.md) - Debugging logs
- [Monitoring](operations/MONITORING.md) - Bugsink, health checks, observability

**NGINX Reference Configs** (in repository root):

- `etc-nginx-sites-available-flyer-crawler.projectium.com` - Production server config
- `etc-nginx-sites-available-flyer-crawler-test-projectium-com.txt` - Test server config

### 🛠️ Tools

External tool configuration:

- [MCP Configuration](tools/MCP-CONFIGURATION.md) - Model Context Protocol servers
- [Bugsink Setup](tools/BUGSINK-SETUP.md) - Error tracking configuration
- [VS Code Setup](tools/VSCODE-SETUP.md) - Editor configuration

### 🤖 AI Agents

Working with Claude Code subagents:

- [Subagent Overview](subagents/OVERVIEW.md) - Introduction to specialized agents
- [Coder Guide](subagents/CODER-GUIDE.md) - Code development patterns
- [Tester Guide](subagents/TESTER-GUIDE.md) - Testing strategies
- [Database Guide](subagents/DATABASE-GUIDE.md) - Database workflows
- [DevOps Guide](subagents/DEVOPS-GUIDE.md) - Deployment and infrastructure
- [AI Usage Guide](subagents/AI-USAGE-GUIDE.md) - Gemini integration
- [Frontend Guide](subagents/FRONTEND-GUIDE.md) - UI/UX development
- [Documentation Guide](subagents/DOCUMENTATION-GUIDE.md) - Writing docs
- [Security & Debug Guide](subagents/SECURITY-DEBUG-GUIDE.md) - Security and debugging

**AI-Optimized References** (token-efficient quick refs):

- [Coder Reference](SUBAGENT-CODER-REFERENCE.md)
- [Tester Reference](SUBAGENT-TESTER-REFERENCE.md)
- [DB Reference](SUBAGENT-DB-REFERENCE.md)
- [DevOps Reference](SUBAGENT-DEVOPS-REFERENCE.md)
- [Integrations Reference](SUBAGENT-INTEGRATIONS-REFERENCE.md)

### 📐 Architecture Decision Records (ADRs)

Design decisions and rationale:

- [ADR Index](adr/index.md) - Complete list of all ADRs
- 54+ ADRs covering patterns, conventions, and technical decisions

### 📦 Archive

Historical and completed documentation:

- [Session Notes](archive/sessions/) - Development session logs
- [Planning Documents](archive/plans/) - Feature plans and implementation status
- [Research Notes](archive/research/) - Investigation and research documents

## Documentation Conventions

- **File Names**: Use SCREAMING_SNAKE_CASE for human-readable docs (e.g., `INSTALL.md`)
- **Links**: Use relative paths from the document's location
- **Code Blocks**: Always specify language for syntax highlighting
- **Tables**: Use markdown tables for structured data
- **Cross-References**: Link to ADRs and other docs for detailed explanations

## Contributing to Documentation

See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines on:

- Writing clear, concise documentation
- Updating docs when code changes
- Creating new ADRs for significant decisions
- Documenting new features and APIs

## Need Help?

- Check the [Testing Guide](development/TESTING.md) for test-related issues
- See [Debugging Guide](development/DEBUGGING.md) for troubleshooting
- Review [ADRs](adr/index.md) for architectural context
- Consult [Subagent Guides](subagents/OVERVIEW.md) for AI agent assistance

## Documentation Maintenance

This documentation is actively maintained. If you find:

- Broken links or outdated information
- Missing documentation for features
- Unclear or confusing sections

Please open an issue or submit a pull request with improvements.