# Binary URL Architecture Mismatch Fix

**Priority**: P2 (New Feature - Critical Fix)
**Source Reference**: From DEVELOPMENT_TODOS.md line 302
**Status**: Ready for Implementation

## Problem Statement

The installation script template uses `/downloads/{platform}` URLs where platform = "linux", but the server only provides files at `/downloads/linux-amd64` and `/downloads/linux-arm64`. This causes binary downloads to fail with 404 errors, resulting in empty or corrupted files that cannot be executed.

## Feature Description

Fix the binary URL architecture mismatch by implementing server-side redirects that handle generic platform requests and redirect them to the appropriate architecture-specific binaries.

## Acceptance Criteria

1. Server should respond to `/downloads/linux` requests with redirects to `/downloads/linux-amd64`
2. Server should maintain backward compatibility for existing installation scripts
3. Installation script should work correctly for x86_64 systems without modification
4. ARM systems should be properly handled with appropriate redirects
5. Error handling should return clear messages for unsupported architectures

## Technical Approach

### Option D: Server-Side Redirect Implementation (Recommended)

1. **Modify Download Handler** (`aggregator-server/internal/api/handlers/downloads.go`)
   - Add route handler for `/downloads/{platform}` where platform is generic ("linux", "windows")
   - Detect client architecture from User-Agent headers or default to x86_64
   - Return HTTP 301 redirect to architecture-specific URL
   - Example: `/downloads/linux` → `/downloads/linux-amd64`

2. **Architecture Detection**
   - Default x86_64 systems to `/downloads/linux-amd64`
   - Use User-Agent parsing for ARM detection when available
   - Fallback to x86_64 for unknown architectures

3. **Error Handling**
   - Return proper 404 for truly unsupported platforms
   - Log redirect attempts for monitoring

## Definition of Done

- ✅ Installation scripts can successfully download binaries using generic platform URLs
- ✅ No 404 errors for x86_64 systems
- ✅ Proper redirect behavior implemented
- ✅ Backward compatibility maintained
- ✅ Error cases handled gracefully
- ✅ Integration testing shows successful agent installations

## Test Plan

1. **Unit Tests**
   - Test redirect handler with various User-Agent strings
   - Test architecture detection logic
   - Test error handling for invalid platforms

2. **Integration Tests**
   - Test complete installation flow using generic URLs
   - Test Linux x86_64 installation (should redirect to amd64)
   - Test Windows x86_64 installation
   - Test error handling for unsupported platforms

3. **Manual Tests**
   - Run installation script on fresh Linux system
   - Verify binary download succeeds
   - Verify agent starts correctly after installation
   - Test with both generic and specific URLs

## Files to Modify

- `aggregator-server/internal/api/handlers/downloads.go` - Add redirect handler
- `aggregator-server/cmd/server/main.go` - Add new route
- Test files for the download handler

## Estimated Effort

- **Development**: 4-6 hours
- **Testing**: 2-3 hours
- **Review**: 1-2 hours

## Dependencies

- None - this is a self-contained server-side fix
- Install script templates can remain unchanged
- Existing architecture-specific download endpoints remain functional

## Risk Assessment

**Low Risk** - This is purely additive functionality that maintains backward compatibility while fixing a critical bug. The redirect pattern is a well-established HTTP pattern with minimal risk of side effects.