# fernandoomelo/gameshelfproject architecture

> Architecture diagram of the GitHub repository fernandoomelo/gameshelfproject, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fernandoomelo/gameshelfproject
- Repository: https://github.com/fernandoomelo/gameshelfproject

## Overview

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: [`apps/api/src/app.ts`](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/app.ts) (Fastify API), [`apps/api/src/modules/lifecycle/routes.ts`](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/lifecycle/routes.ts) (Game lifecycle), [`apps/web/src/pages/app.tsx`](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/web/src/pages/app.tsx) (Web app), [`apps/api/src/modules/integrations/sync-runner.ts`](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/integrations/sync-runner.ts) (Achievist sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User experience"]
  node_web["Web app<br/>[app.tsx]"]
  node_offline["Offline sessions"]
end

subgraph group_catalog["Library management"]
  node_games["Game catalog<br/>[repository.ts]"]
  node_platforms["Platform catalog<br/>[repository.ts]"]
  node_backlog["Backlog and lists<br/>[repository.ts]"]
  node_metadata["Metadata lookup"]
end

subgraph group_tracking["Play tracking"]
  node_sessions["Session history<br/>[repository.ts]"]
  node_playthroughs["Playthroughs<br/>[service.ts]"]
  node_lifecycle["Game lifecycle<br/>[routes.ts]"]
  node_challenges["Challenges and goals<br/>[service.ts]"]
end

subgraph group_insights["Insights and integrations"]
  node_dashboard["Dashboard<br/>[service.ts]"]
  node_reports["Reports<br/>[routes.ts]"]
  node_stats["Activity and stats<br/>[routes.ts]"]
  node_backup["Backup import/export<br/>[routes.ts]"]
  node_achievist["Achievist sync<br/>[sync-runner.ts]"]
  node_external["Achievist service"]
end

subgraph group_platform["API and persistence"]
  node_api["Fastify API<br/>[app.ts]"]
  node_contracts["Shared contracts<br/>[index.ts]"]
  node_database[("PostgreSQL schema<br/>[index.ts]")]
end

node_user(("Player"))

node_user -->|"manages library"| node_web
node_web -->|"uses API"| node_api
node_web -.->|"records offline"| node_offline
node_api -.->|"validates data"| node_contracts
node_api -.->|"persists data"| node_database
node_api -.->|"serves catalog"| node_games
node_api -.->|"serves platforms"| node_platforms
node_api -->|"serves backlog"| node_backlog
node_api -.->|"looks up metadata"| node_metadata
node_api -->|"serves sessions"| node_sessions
node_api -->|"serves playthroughs"| node_playthroughs
node_api -->|"routes lifecycle"| node_lifecycle
node_lifecycle -->|"reads and updates"| node_playthroughs
node_lifecycle -->|"reads sessions"| node_sessions
node_lifecycle -->|"records completion"| node_challenges
node_api -.->|"serves dashboard"| node_dashboard
node_api -->|"serves reports"| node_reports
node_api -->|"serves statistics"| node_stats
node_api -->|"exports and imports"| node_backup
node_api -.->|"runs sync"| node_achievist
node_achievist -.->|"fetches library"| node_external
node_user -->|"starts manual sync"| node_achievist

click node_web "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/web/src/pages/app.tsx"
click node_offline "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/web/src/pages/offline-sessions.ts"
click node_api "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/app.ts"
click node_contracts "https://github.com/fernandoomelo/gameshelfproject/blob/master/packages/contracts/src/index.ts"
click node_database "https://github.com/fernandoomelo/gameshelfproject/blob/master/packages/database/src/schema/index.ts"
click node_games "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/games/repository.ts"
click node_platforms "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/platforms/repository.ts"
click node_backlog "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/backlog/repository.ts"
click node_metadata "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/games/metadata-provider.ts"
click node_sessions "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/sessions/repository.ts"
click node_playthroughs "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/playthroughs/service.ts"
click node_lifecycle "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/lifecycle/routes.ts"
click node_challenges "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/challenge/service.ts"
click node_dashboard "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/dashboard/service.ts"
click node_reports "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/reports/routes.ts"
click node_stats "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/stats/routes.ts"
click node_backup "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/backup/routes.ts"
click node_achievist "https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/integrations/sync-runner.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_offline toneBlue
class node_games,node_platforms,node_backlog,node_metadata toneAmber
class node_sessions,node_playthroughs,node_lifecycle,node_challenges toneMint
class node_dashboard,node_reports,node_stats,node_backup,node_achievist,node_external toneRose
class node_api,node_contracts,node_database,node_user toneIndigo
```

## Components

### User experience

- [Web app](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/web/src/pages/app.tsx): `apps/web/src/pages/app.tsx`
- [Offline sessions](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/web/src/pages/offline-sessions.ts): `apps/web/src/pages/offline-sessions.ts`

### Library management

- [Game catalog](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/games/repository.ts): `apps/api/src/modules/games/repository.ts`
- [Platform catalog](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/platforms/repository.ts): `apps/api/src/modules/platforms/repository.ts`
- [Backlog and lists](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/backlog/repository.ts): `apps/api/src/modules/backlog/repository.ts`
- [Metadata lookup](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/games/metadata-provider.ts): `apps/api/src/modules/games/metadata-provider.ts`

### Play tracking

- [Session history](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/sessions/repository.ts): `apps/api/src/modules/sessions/repository.ts`
- [Playthroughs](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/playthroughs/service.ts): `apps/api/src/modules/playthroughs/service.ts`
- [Game lifecycle](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/lifecycle/routes.ts): `apps/api/src/modules/lifecycle/routes.ts`
- [Challenges and goals](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/challenge/service.ts): `apps/api/src/modules/challenge/service.ts`

### Insights and integrations

- [Dashboard](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/dashboard/service.ts): `apps/api/src/modules/dashboard/service.ts`
- [Reports](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/reports/routes.ts): `apps/api/src/modules/reports/routes.ts`
- [Activity and stats](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/stats/routes.ts): `apps/api/src/modules/stats/routes.ts`
- [Backup import/export](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/backup/routes.ts): `apps/api/src/modules/backup/routes.ts`
- [Achievist sync](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/modules/integrations/sync-runner.ts): `apps/api/src/modules/integrations/sync-runner.ts`
- **Achievist service**

### API and persistence

- [Fastify API](https://github.com/fernandoomelo/gameshelfproject/blob/master/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Shared contracts](https://github.com/fernandoomelo/gameshelfproject/blob/master/packages/contracts/src/index.ts): `packages/contracts/src/index.ts`
- [PostgreSQL schema](https://github.com/fernandoomelo/gameshelfproject/blob/master/packages/database/src/schema/index.ts): `packages/database/src/schema/index.ts`

### Other components

- **Player**

## Connections

- Player → Web app: manages library (evidence: `README.md`)
- Web app → Fastify API: uses API (evidence: `README.md`)
- Web app → Offline sessions: records offline (evidence: `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 (evidence: `apps/api/src/modules/lifecycle/routes.ts`)
- Game lifecycle → Playthroughs: reads and updates (evidence: `apps/api/src/modules/lifecycle/routes.ts`)
- Game lifecycle → Session history: reads sessions (evidence: `apps/api/src/modules/lifecycle/routes.ts`)
- Game lifecycle → Challenges and goals: records completion (evidence: `apps/api/src/modules/lifecycle/routes.ts`)
- Fastify API → Dashboard: serves dashboard
- Fastify API → Reports: serves reports (evidence: `apps/api/src/modules/reports/routes.ts`)
- Fastify API → Activity and stats: serves statistics (evidence: `apps/api/src/modules/stats/routes.ts`)
- Fastify API → Backup import/export: exports and imports (evidence: `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 (evidence: `README.md`)