A CLI and web application for tracking and analyzing your RetroAchievements games.
/achieve
├── src/
│ ├── config.py # Centralized configuration
│ ├── cache.py # Caching system with TTL support
│ ├── api/
│ │ └── retroachievements.py # All RetroAchievements API calls (cached)
│ ├── services/
│ │ └── game_analysis.py # Business logic for game analysis
│ ├── cli/
│ │ └── commands.py # CLI interface
│ └── web/
│ ├── app.py # Flask app factory
│ └── routes.py # Web routes
├── templates/ # HTML templates
├── static/ # CSS and static assets
├── .cache/ # Cache storage (auto-generated)
├── main.py # CLI entry point
├── app.py # Web app entry point
├── manage_cache.py # Cache management utility
├── requirements.txt
└── .env # API credentials (not in git)
- Install dependencies:
pip install -r requirements.txt- Create a
.envfile with your credentials:
RA_API_KEY=your_api_key
RA_USERNAME=your_username
Run the command-line interface:
source venv/bin/activate
python main.pyFeatures:
- [0] View Profile: See your stats, rank, points, and achievements
- [1] Close to Completion: Games with 10%+ progress (top 10)
- [2] Incomplete Games: Games 50%+ complete, or all incomplete if none (top 20)
- [3] Easy to Master: Find easiest games by console (top 10)
- [4] Exit: Quit the application
All data is cached for performance - first run may be slower.
Run the Flask web server:
source venv/bin/activate
python app.pyThen visit http://localhost:5000 in your browser.
Features:
- Home (/): Profile dashboard with your stats
- Close to Completion: Games with 10%+ progress
- Incomplete Games: Games 50%+ complete with smart fallback
- Easy to Master: Select console and see easiest games
- All data cached for instant page loads
Both CLI and web versions provide identical functionality with the same logic and thresholds. See CLI_WEB_COMPARISON.md for details.
The application includes an intelligent caching system to improve performance and reduce API load.
| Data Type | Cache Duration | Reason |
|---|---|---|
| Console list | 7 days | Static data, rarely changes |
| Game lists | 24 hours | Infrequently updated |
| Game details | 1 hour | Mastery rates change slowly |
| User completed games | 10 minutes | Updates when you complete games |
| User summary | 10 minutes | Personal stats update periodically |
| Recently played | 2 minutes | Frequently changing data |
- 50x faster API responses on cached data
- "Easy to master" feature: dramatically faster (50+ API calls → cached)
- Reduced load on RetroAchievements servers
- Works offline with cached data
View cache statistics:
python manage_cache.py infoClear all cache:
python manage_cache.py clearClear expired entries only:
python manage_cache.py clear-expiredThe cache is stored in .cache/ directory and is automatically managed with TTL (Time To Live) expiration.
- config.py: Environment variables, constants, and configuration
- cache.py: File-based caching system with automatic TTL expiration
- api/retroachievements.py: All HTTP requests to RetroAchievements API (with caching)
- services/game_analysis.py: Business logic (calculations, filtering, sorting)
- cli/commands.py: Terminal UI and user interaction
- web/app.py: Flask application setup
- web/routes.py: HTTP routes and request handling
- Single Source of Truth: API functions defined once, used everywhere
- Performance: Intelligent caching reduces API calls by 50-100x
- Testability: Each module has a single responsibility
- Maintainability: Changes to business logic don't affect presentation
- Reusability: Services can be used by both CLI and web interfaces
- Scalability: Easy to add new features or interfaces
Old files have been backed up to old_files/ directory and can be safely deleted after verification.