# 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*