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>
143 lines
5.7 KiB
Markdown
143 lines
5.7 KiB
Markdown
# 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
|
|
|
|
**PM2 Management**:
|
|
|
|
- [PM2 Namespace Completion Report](operations/PM2-NAMESPACE-COMPLETION-REPORT.md) - PM2 namespace implementation project summary
|
|
- [PM2 Incident Response Runbook](operations/PM2-INCIDENT-RESPONSE.md) - Step-by-step procedures for PM2 incidents
|
|
- [PM2 Crash Debugging](operations/PM2-CRASH-DEBUGGING.md) - Troubleshooting PM2 crashes
|
|
|
|
**Incident Reports**:
|
|
|
|
- [2026-02-17 PM2 Process Kill](operations/INCIDENT-2026-02-17-PM2-PROCESS-KILL.md) - 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 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.
|