Torben Sorensen
07125fc99d
All checks were successful
Deploy to Test Environment / deploy-to-test (push) Successful in 56m40s
Add missing namespace flags to pm2 save commands and comprehensive tests to ensure complete isolation between production, test, and dev environments. ## Changes Made ### Workflow Fixes - restart-pm2.yml: Add --namespace flags to pm2 save (lines 45, 69) - manual-db-restore.yml: Add --namespace flag to pm2 save (line 95) ### Test Enhancements - Add 6 new tests to validate ALL pm2 save commands have namespace flags - Total test suite: 89 tests (all passing) - Specific validation for each workflow file ### Documentation - Create comprehensive PM2 Namespace Completion Report - Update docs/README.md with PM2 Management section - Cross-reference with ADR-063 and migration script ## Benefits - Eliminates pm2 save race conditions between environments - Enables safe parallel test and production deployments - Simplifies process management with namespace isolation - Prevents incidents like 2026-02-17 PM2 process kill ## Test Results All 89 tests pass: - 21 ecosystem config tests - 38 workflow file tests - 6 pm2 save validation tests - 15 migration script tests - 15 documentation tests - 3 end-to-end consistency tests Verified in dev container with vitest. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
5.7 KiB
5.7 KiB
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
PM2 Management:
- PM2 Namespace Completion Report - PM2 namespace implementation project summary
- PM2 Incident Response Runbook - Step-by-step procedures for PM2 incidents
- PM2 Crash Debugging - Troubleshooting PM2 crashes
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.