Redflag/docs/2_ARCHITECTURE/implementation/CODE_ARCHITECT_BRIEFING.md

Code-Architect Agent Briefing: RedFlag Directory Structure Migration

Context for Architecture Design

Problem Statement

RedFlag has inconsistent directory paths between components that need to be unified into a nested structure. The current state has:

• Path inconsistencies between main.go, cache system, migration system, and installer
• Security vulnerability: systemd ReadWritePaths don't match actual write locations
• Migration path inconsistencies (2 different backup patterns)
• Legacy v0.1.18 uses /etc/aggregator and /var/lib/aggregator

Two Plans Analyzed

Plan A: Original Comprehensive Plan (6h 50m)

• Assumed need to handle broken intermediate versions v0.1.19-v0.1.23
• Complex migration logic for multiple legacy states
• Over-engineered for actual requirements

Plan B: Simplified Plan (3h 30m) ⭐ SELECTED

• Based on discovery: Legacy v0.1.18 is only version in the wild (~20 users)
• No intermediate broken versions exist publicly
• Single migration path: v0.1.18 → v0.2.0
• Reasoning: Aligns with Ethos #3 (Resilience - don't over-engineer) and #5 (No BS - simplicity over complexity)

Target Architecture (Nested Structure)

CRITICAL: BOTH /var/lib AND /etc paths need nesting

# Data directories (state, cache, backups)
/var/lib/redflag/
├── agent/
│   ├── cache/              # Scan result cache
│   ├── state/              # Acknowledgments, circuit breaker state
│   └── migration_backups/  # Pre-migration backups
└── server/                 # (Future) Server component

# Configuration directories
/etc/redflag/
├── agent/
│   └── config.json         # Agent configuration
└── server/
    └── config.json         # (Future) Server configuration

# Log directories
/var/log/redflag/
├── agent/
│   └── agent.log           # Agent logs
└── server/
    └── server.log          # (Future) Server logs

Why BOTH need nesting:

• Aligns with data directory structure
• Clear component separation for troubleshooting
• Future-proof when server component is on same machine
• Consistency in path organization (everything under /{base}/{component}/)
• Ethos #5: Tells honest truth about architecture

Components Requiring Updates

Agent Code (Go):

1. aggregator-agent/cmd/agent/main.go - Remove hardcoded paths, use constants
2. aggregator-agent/internal/cache/local.go - Update cache directory
3. aggregator-agent/internal/acknowledgment/tracker.go - Update state directory
4. aggregator-agent/internal/config/config.go - Use constants
5. aggregator-agent/internal/constants/paths.go - NEW: Centralized path definitions
6. aggregator-agent/internal/migration/detection.go - Simplified v0.1.18 only migration
7. aggregator-agent/internal/migration/executor.go - Execute migration to nested paths

Server/Installer: 8. aggregator-server/internal/services/templates/install/scripts/linux.sh.tmpl - Create nested dirs, update systemd paths

Version: 9. aggregator-agent/cmd/agent/main.go - Update version to v0.2.0

Path Mappings for Migration

Legacy v0.1.18 → v0.2.0

Config files:

• FROM: /etc/aggregator/config.json
• TO: /etc/redflag/agent/config.json

State files:

• FROM: /var/lib/aggregator/*
• TO: /var/lib/redflag/agent/state/*

Other paths:

• Cache: /var/lib/redflag/agent/cache/last_scan.json (fresh start okay)
• Log: /var/log/redflag/agent/agent.log (new location)

Cross-Platform Considerations

Linux:

• Base: /var/lib/redflag/, /etc/redflag/, /var/log/redflag/
• Agent: /var/lib/redflag/agent/, /etc/redflag/agent/, /var/log/redflag/agent/

Windows:

• Base: C:\ProgramData\RedFlag\
• Agent: C:\ProgramData\RedFlag\agent\

Migration only needed on Linux - Windows installs are fresh (no legacy v0.1.18)

Design Requirements

Architecture Characteristics:

• ✅ Maintainable: Single source of truth (constants package)
• ✅ Resilient: Clear component isolation, proper systemd isolation
• ✅ Honest: Path structure reflects actual architecture
• ✅ Future-proof: Ready for server component
• ✅ Simple: Only handles v0.1.18 → v0.2.0, no intermediate broken states

Security Requirements:

• Proper ReadWritePaths in systemd service
• File permissions maintained (600 for config, 755 for dirs)
• No new unauthenticated endpoints
• Rollback capability in migration

Quality Requirements:

• Error logging throughout migration
• Idempotent operations
• Backup before migration
• Test coverage for fresh installs AND migration

Files to Read for Full Understanding

1. aggregator-agent/cmd/agent/main.go - Main entry point, current broken getStatePath()
2. aggregator-agent/internal/cache/local.go - Cache operations, hardcoded CacheDir
3. aggregator-agent/internal/acknowledgment/tracker.go - State persistence
4. aggregator-agent/internal/migration/detection.go - Current v0.1.18 detection logic
5. aggregator-server/internal/services/templates/install/scripts/linux.sh.tmpl - Installer and systemd service
6. aggregator-agent/internal/config/config.go - Config loading/saving
7. /home/casey/Projects/RedFlag (Legacy)/aggregator-agent/cmd/agent/main.go - Legacy v0.1.18 paths for reference

Migration Logic Requirements

Before migration:

1. Check for v0.1.18 legacy: /etc/aggregator/config.json
2. Create backup: /var/lib/redflag/agent/migration_backups/pre_v0.2.0_<timestamp>/
3. Copy config, state to backup

Migration steps:

1. Create nested directories: /etc/redflag/agent/, /var/lib/redflag/agent/{cache,state}/
2. Move config: /etc/aggregator/config.json → /etc/redflag/agent/config.json
3. Move state: /var/lib/aggregator/* → /var/lib/redflag/agent/state/
4. Update file ownership/permissions
5. Remove empty legacy directories
6. Log completion

Rollback on failure:

1. Stop agent
2. Restore from backup
3. Start agent
4. Log rollback

Testing Requirements

Fresh installation tests:

• All directories created correctly
• Config written to /etc/redflag/agent/config.json
• Agent runs and persists state correctly
• Systemd ReadWritePaths work correctly

Migration test:

• Create v0.1.18 structure
• Install/run new agent
• Verify migration succeeds
• Verify agent runs with migrated data
• Test rollback by simulating failure

Cross-platform:

• Linux: Full migration path tested
• Windows: Fresh install tested (no migration needed)

Timeline & Approach to Recommend

Recommended: 4 sessions × 50-55 minutes

• Session 1: Constants + main.go updates
• Session 2: Cache, config, acknowledgment updates
• Session 3: Migration system + installer updates
• Session 4: Testing and refinements

Or: Single focused session of 3.5 hours with coffee

Critical: Both /var/lib and /etc Need Nesting

Make explicit in your design:

• Config paths must change from /etc/redflag/config.json to /etc/redflag/agent/config.json
• This is a breaking change and requires migration
• Server component in future will use /etc/redflag/server/config.json
• This creates parallel structure to /var/lib/redflag/{agent,server}/

Design principle: Everything under {base}/{component}/{resource}

• Base: /var/lib/redflag or /etc/redflag
• Component: agent or server
• Resource: cache, state, config.json, etc.

This alignment is crucial for maintainability and aligns with Ethos #5 (No BS - honest structure).

---

Ready for architecture design, code-architect. We've done the homework - now build the blueprint.

- Ani, having analyzed both plans and verified legacy state