---
alwaysApply: true
---

# SteamCache2 Project Structure Guide

This is a high-performance Steam download cache written in Go. The main entry point is [main.go](mdc:main.go), which delegates to the command structure in [cmd/](mdc:cmd/).

## Core Architecture

- **Main Entry**: [main.go](mdc:main.go) - Simple entry point that calls `cmd.Execute()`
- **Command Layer**: [cmd/root.go](mdc:cmd/root.go) - CLI interface using Cobra, handles configuration loading and service startup
- **Core Service**: [steamcache/steamcache.go](mdc:steamcache/steamcache.go) - Main HTTP proxy and caching logic
- **Configuration**: [config/config.go](mdc:config/config.go) - YAML-based configuration management
- **Virtual File System**: [vfs/](mdc:vfs/) - Abstracted storage layer supporting memory and disk caches

## Key Components

### VFS (Virtual File System)
- [vfs/vfs.go](mdc:vfs/vfs.go) - Core VFS interface
- [vfs/memory/](mdc:vfs/memory/) - In-memory cache implementation
- [vfs/disk/](mdc:vfs/disk/) - Disk-based cache implementation
- [vfs/cache/](mdc:vfs/cache/) - Cache coordination layer
- [vfs/gc/](mdc:vfs/gc/) - Garbage collection algorithms (LRU, LFU, FIFO, etc.)

### Service Management
- Service detection via User-Agent patterns
- Support for multiple gaming services (Steam, Epic, etc.)
- SHA256-based cache key generation with service prefixes

### Advanced Features
- [vfs/adaptive/](mdc:vfs/adaptive/) - Adaptive caching strategies
- [vfs/predictive/](mdc:vfs/predictive/) - Predictive cache warming
- Request coalescing for concurrent downloads
- Range request support for partial content

## Development Workflow

Use the [Makefile](mdc:Makefile) for development:
- `make` - Run tests and build
- `make test` - Run all tests
- `make run` - Run the application
- `make run-debug` - Run with debug logging

## Testing

- Unit tests: [steamcache/steamcache_test.go](mdc:steamcache/steamcache_test.go)
- Integration tests: [steamcache/integration_test.go](mdc:steamcache/integration_test.go)
- Test cache data: [steamcache/test_cache/](mdc:steamcache/test_cache/)

## Configuration

Default configuration is generated in [config.yaml](mdc:config.yaml) on first run. The application supports:
- Memory and disk cache sizing
- Garbage collection algorithm selection
- Concurrency limits
- Upstream server configuration