206 lines
7.5 KiB
Markdown
206 lines
7.5 KiB
Markdown
# 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*
|