- Python 75.7%
- TypeScript 21.3%
- CSS 1.5%
- Dockerfile 0.7%
- Mako 0.4%
- Other 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .vscode | ||
| backend | ||
| docs | ||
| frontend | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| compose.yml | ||
| README.md | ||
GameLens
Analyses a Steam profile, surfaces gaming patterns, recommends underplayed owned games, and suggests similar titles available on external sellers.
Phase 0–5 complete: Compose (postgres + api), Alembic migrations, Steam profile API (1h cache), categories (by_engagement + by_genre), Fanatical + GMG deals (GET /deals/{game_name}, 24h cache), APScheduler jobs, recommendations (GET /user/{steam_id}/recommendations), CORS for the local Next.js UI, and frontend (/ SteamID64 entry → /u/[steamId] results). Next: Phase 6 — see docs/plan.md.
Quick start
cp .env.example .env
# Required: set STEAM_API_KEY (https://steamcommunity.com/dev/apikey)
docker compose up --build -d
curl -fsS http://127.0.0.1:8081/health
curl -fsS "http://127.0.0.1:8081/user/<steam_id64>/profile"
curl -fsS "http://127.0.0.1:8081/user/<steam_id64>/categories"
curl -fsS "http://127.0.0.1:8081/deals/Farming%20Simulator%2025"
curl -fsS "http://127.0.0.1:8081/user/<steam_id64>/recommendations"
Requires Docker. Compose runs alembic upgrade head before the API starts.
Without Docker, run the API locally:
cd backend && uv sync --all-extras
export DATABASE_URL=postgresql+asyncpg://gamelens:gamelens@127.0.0.1:5432/gamelens
export STEAM_API_KEY=...
uv run alembic upgrade head
uv run uvicorn gamelens.main:app --port 8081
APScheduler runs inside the API process: profile refresh (default cron 0 3 * * *, profiles older than 24h) and catalog deal scrape (default 30 4 * * *). One-shot CLIs: cd backend && uv run python -m gamelens.jobs.refresh_profiles / uv run python -m gamelens.jobs.scrape_deals. Disable with PROFILE_REFRESH_ENABLED=false / DEAL_SCRAPE_ENABLED=false.
Frontend (local only; not in Compose yet). API CORS defaults allow http://localhost:3000 and http://127.0.0.1:3000 (CORS_ORIGINS):
cd frontend && npm install && npm run dev
# optional: cp frontend/.env.example frontend/.env
# UI → http://localhost:3000 (API default http://127.0.0.1:8081)
Layout
| Path | Role |
|---|---|
backend/ |
FastAPI app (/health, profile, categories, deals, recommendations) |
frontend/ |
Next.js UI (SteamID64 → profile / recs / deals) |
compose.yml |
PostgreSQL 16 + API |
.env.example |
Secrets template (STEAM_API_KEY, DB, ports, CORS, refresh/deal/rec knobs) |
docs/ |
Requirements, stack, plan, architecture, roadmap, loadtest baseline |
Branching
main— stabledev— integration
Feature branches merge into dev, then dev into main.
Documentation
| Document | Description |
|---|---|
| docs/requirements.md | Requirements v1.0 — scope, user stories, success criteria |
| docs/stack.md | Tech stack decision and repo conventions |
| docs/plan.md | Phased implementation plan — goals, tasks, exit criteria |
| docs/architecture.md | System architecture, components, data flow |
| docs/roadmap.md | Task tables, tools, deliverables, week estimates |
| docs/loadtest-baseline.md | Phase 4 Locust recommendation-read baseline |
Full index: docs/README.md. Backend details: backend/README.md.