Torben Sorensen
441467eb8a
All checks were successful
Deploy to Test Environment / deploy-to-test (push) Successful in 26m39s
Implements efficient version synchronization between production and test environments without running the full test deployment pipeline. Problem: - Production version bumps triggered full 5-7 minute test deployment - Wasteful: 95% less CPU, 99.8% less file I/O needed - Code already tested when originally pushed to main Solution (matching stock-alert architecture): - New sync-test-version.yml workflow (~30 seconds) - Triggers automatically after successful production deployment - Updates only package.json in test directory - Restarts PM2 with --update-env to refresh version metadata Benefits: - 90% faster (30 sec vs 5-7 min) - Saves ~20 minutes/month of CI time - Clean separation: no conditionals polluting deploy-to-test.yml - Same end state, optimized path Changes: - Added .gitea/workflows/sync-test-version.yml (new workflow) - Added docs/adr/0062-lightweight-version-sync-workflow.md (decision record) - Updated docs/adr/index.md (ADR catalog) - Cleaned up duplicate TSOA generation step in deploy-to-test.yml Architecture: - deploy-to-test.yml: unchanged (runs on code changes) - deploy-to-prod.yml: unchanged (no explicit trigger needed) - sync-test-version.yml: auto-triggers via workflow_run Related: - Inspired by stock-alert project optimization (commit 021f9c8) - ADR-061: PM2 Process Isolation Safeguards Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
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
Incident Response:
- PM2 Incident Response Runbook - Step-by-step procedures for PM2 incidents
Incident Reports:
- 2026-02-17 PM2 Process Kill - ALL PM2 processes killed during v0.15.0 deployment (Mitigated)
NGINX Reference Configs (in repository root):
etc-nginx-sites-available-flyer-crawler.projectium.com- Production server configetc-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):
📐 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.