How fernandoomelo/gameshelfproject works
GameShelf is a self-hosted, local-first game library and planning app. A user manages a game library in the web app, records sessions and playthroughs, and uses dashboard, reports, and planning views to understand progress. The API separates catalog, play tracking, lifecycle, and analysis capabilities; PostgreSQL persists application data. Backup, offline session capture, metadata lookup, and Achievist synchronization are additional branches. Relationships below follow the README or shown imports/calls; unsampled wiring is omitted or marked unverified.
Main entry points: app.ts Fastify API · routes.ts Game lifecycle · app.tsx Web app · sync-runner.ts Achievist sync
Components 20
User experience
- Web app
apps/web/src/pages/app.tsx - Offline sessions
apps/web/src/pages/offline-sessions.ts
Library management
- Game catalog
apps/api/src/modules/games/repository.ts - Platform catalog
apps/api/src/modules/platforms/repository.ts - Backlog and lists
apps/api/src/modules/backlog/repository.ts - Metadata lookup
apps/api/src/modules/games/metadata-provider.ts
Play tracking
- Session history
apps/api/src/modules/sessions/repository.ts - Playthroughs
apps/api/src/modules/playthroughs/service.ts - Game lifecycle
apps/api/src/modules/lifecycle/routes.ts - Challenges and goals
apps/api/src/modules/challenge/service.ts
Insights and integrations
- Dashboard
apps/api/src/modules/dashboard/service.ts - Reports
apps/api/src/modules/reports/routes.ts - Activity and stats
apps/api/src/modules/stats/routes.ts - Backup import/export
apps/api/src/modules/backup/routes.ts - Achievist sync
apps/api/src/modules/integrations/sync-runner.ts - Achievist service
API and persistence
- Fastify API
apps/api/src/app.ts - Shared contracts
packages/contracts/src/index.ts - PostgreSQL schema
packages/database/src/schema/index.ts
Other components
- Player
Connections 22
- Player → Web app: manages library
README.md - Web app → Fastify API: uses API
README.md - Web app → Offline sessions: records offline
apps/web/src/pages/app.tsx - Fastify API → Shared contracts: validates data
- Fastify API → PostgreSQL schema: persists data
- Fastify API → Game catalog: serves catalog
- Fastify API → Platform catalog: serves platforms
- Fastify API → Backlog and lists: serves backlog
- Fastify API → Metadata lookup: looks up metadata
- Fastify API → Session history: serves sessions
- Fastify API → Playthroughs: serves playthroughs
- Fastify API → Game lifecycle: routes lifecycle
apps/api/src/modules/lifecycle/routes.ts - Game lifecycle → Playthroughs: reads and updates
apps/api/src/modules/lifecycle/routes.ts - Game lifecycle → Session history: reads sessions
apps/api/src/modules/lifecycle/routes.ts - Game lifecycle → Challenges and goals: records completion
apps/api/src/modules/lifecycle/routes.ts - Fastify API → Dashboard: serves dashboard
- Fastify API → Reports: serves reports
apps/api/src/modules/reports/routes.ts - Fastify API → Activity and stats: serves statistics
apps/api/src/modules/stats/routes.ts - Fastify API → Backup import/export: exports and imports
apps/api/src/modules/backup/routes.ts - Fastify API → Achievist sync: runs sync
- Achievist sync → Achievist service: fetches library
- Player → Achievist sync: starts manual sync
README.md