flyer-crawler.projectium.com/docs/README.md

Flyer Crawler Documentation

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

Quick Links

• Main README - Project overview and quick start
• CLAUDE.md - AI agent instructions and project guidelines
• CONTRIBUTING.md - Development workflow and contribution guide

Documentation Structure

🚀 Getting Started

New to the project? Start here:

• Installation Guide - Complete setup instructions
• Environment Configuration - Environment variables and secrets

🏗️ Architecture

Understand how the system works:

• System Overview - High-level architecture
• Database Schema - Database design and entities
• Authentication - OAuth and JWT authentication
• WebSocket Usage - Real-time communication patterns

💻 Development

Day-to-day development guides:

• Testing Guide - Unit, integration, and E2E testing
• Code Patterns - Common code patterns and ADR examples
• API Versioning - API versioning infrastructure and workflows
• Design Tokens - UI design system and Neo-Brutalism
• Debugging Guide - Common debugging patterns
• Dev Container - Development container setup and PM2

🔧 Operations

Production operations and deployment:

• Deployment Guide - Deployment procedures
• Bare Metal Setup - Server provisioning
• Logstash Quick Reference - Log aggregation
• Logstash Troubleshooting - Debugging logs
• Monitoring - 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 - Model Context Protocol servers
• Bugsink Setup - Error tracking configuration
• VS Code Setup - Editor configuration

🤖 AI Agents

Working with Claude Code subagents:

• Subagent Overview - Introduction to specialized agents
• Coder Guide - Code development patterns
• Tester Guide - Testing strategies
• Database Guide - Database workflows
• DevOps Guide - Deployment and infrastructure
• AI Usage Guide - Gemini integration
• Frontend Guide - UI/UX development
• Documentation Guide - Writing docs
• Security & Debug Guide - Security and debugging

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

• Coder Reference
• Tester Reference
• DB Reference
• DevOps Reference
• Integrations Reference

📐 Architecture Decision Records (ADRs)

Design decisions and rationale:

• ADR Index - Complete list of all ADRs
• 54+ ADRs covering patterns, conventions, and technical decisions

📦 Archive

Historical and completed documentation:

• Session Notes - Development session logs
• Planning Documents - Feature plans and implementation status
• Research Notes - 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 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 for test-related issues
• See Debugging Guide for troubleshooting
• Review ADRs for architectural context
• Consult Subagent Guides 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.