# poppa/mtrek architecture

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

- Interactive diagram: https://gitdiagram.com/poppa/mtrek
- Repository: https://github.com/poppa/mtrek

## Overview

MTrek is a collaborative music-exploration app: users create or join a Trek, explore its year-based or curated-album rounds, select and rate albums, and view rankings and round history. Server route handlers enforce the user workflow and delegate Trek operations to the domain service, which uses PostgreSQL; album search is a separate Spotify integration. The README documents both Trek types and their progression rules. Some subsystem wiring is represented only where supported by the sampled routes or README.

Main entry points: [`src/lib/server/trek-service.ts`](https://github.com/poppa/mtrek/blob/develop/src/lib/server/trek-service.ts) (Trek service), [`src/lib/server/session.ts`](https://github.com/poppa/mtrek/blob/develop/src/lib/server/session.ts) (Session helpers), [`src/routes/+page.server.ts`](https://github.com/poppa/mtrek/blob/develop/src/routes/%2Bpage.server.ts) (Trek home), [`src/routes/treks/[trekId]/+page.server.ts`](https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/%2Bpage.server.ts) (Trek workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workflows"]
  node_home["Trek home<br/>[+page.server.ts]"]
  node_trek["Trek workspace<br/>[+page.server.ts]"]
  node_invite["Invite and join<br/>[+page.server.ts]"]
  node_round["Round history<br/>[+page.server.ts]"]
  node_year["Year exploration<br/>[+page.server.ts]"]
  node_rankings["Trek rankings<br/>[+page.server.ts]"]
  node_year_ranking["Year rankings<br/>[+page.server.ts]"]
  node_profile["User profile<br/>[+page.server.ts]"]
  node_user_rankings["User rankings<br/>[+page.server.ts]"]
end

subgraph group_domain["Trek domain"]
  node_trek_service["Trek service<br/>[trek-service.ts]"]
  node_ranking_logic["Ranking logic<br/>[ranking.ts]"]
end

subgraph group_identity["Identity and search"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_session["Session helpers<br/>[session.ts]"]
  node_spotify_route["Album search route<br/>[+server.ts]"]
  node_spotify["Spotify client<br/>[spotify.ts]"]
end

subgraph group_data["Persistence"]
  node_db[("PostgreSQL<br/>[index.ts]")]
  node_schema["Database schema<br/>[schema.ts]"]
end

node_participant(("Participant"))
node_oauth(("OAuth providers"))
node_spotify_api(("Spotify Web API"))

node_participant -->|"uses"| node_home
node_participant -->|"manages rounds"| node_trek
node_participant -->|"joins Trek"| node_invite
node_participant -->|"views"| node_rankings
node_participant -->|"views"| node_profile
node_home -->|"requires identity"| node_session
node_home -->|"creates and lists"| node_trek_service
node_trek -->|"checks access"| node_session
node_trek -->|"loads and updates"| node_trek_service
node_invite -->|"looks up and joins"| node_trek_service
node_year -->|"loads year"| node_trek_service
node_round -->|"loads round"| node_trek_service
node_rankings -->|"loads albums"| node_trek_service
node_year_ranking -->|"loads years"| node_trek_service
node_profile -->|"loads profile data"| node_trek_service
node_user_rankings -->|"loads user rankings"| node_trek_service
node_trek_service -->|"reads and writes"| node_db
node_db -->|"implements"| node_schema
node_rankings -.->|"uses ranking"| node_ranking_logic
node_year_ranking -.->|"uses ranking"| node_ranking_logic
node_auth -->|"authenticates with"| node_oauth
node_session -->|"reads session"| node_auth
node_spotify_route -->|"searches albums"| node_spotify
node_spotify_route -->|"checks identity"| node_session
node_spotify -->|"queries"| node_spotify_api

click node_home "https://github.com/poppa/mtrek/blob/develop/src/routes/%2Bpage.server.ts"
click node_trek "https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/%2Bpage.server.ts"
click node_invite "https://github.com/poppa/mtrek/blob/develop/src/routes/join/%5BinviteCode%5D/%2Bpage.server.ts"
click node_round "https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/rounds/%5BroundId%5D/%2Bpage.server.ts"
click node_year "https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/years/%5Byear%5D/%2Bpage.server.ts"
click node_rankings "https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/album-ranking/%2Bpage.server.ts"
click node_year_ranking "https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/year-ranking/%2Bpage.server.ts"
click node_profile "https://github.com/poppa/mtrek/blob/develop/src/routes/user/%5BuserId%5D/%2Bpage.server.ts"
click node_user_rankings "https://github.com/poppa/mtrek/blob/develop/src/routes/user/%5BuserId%5D/album-ranking/%2Bpage.server.ts"
click node_trek_service "https://github.com/poppa/mtrek/blob/develop/src/lib/server/trek-service.ts"
click node_ranking_logic "https://github.com/poppa/mtrek/blob/develop/src/lib/ranking.ts"
click node_auth "https://github.com/poppa/mtrek/blob/develop/src/auth.ts"
click node_session "https://github.com/poppa/mtrek/blob/develop/src/lib/server/session.ts"
click node_spotify_route "https://github.com/poppa/mtrek/blob/develop/src/routes/api/spotify/search/%2Bserver.ts"
click node_spotify "https://github.com/poppa/mtrek/blob/develop/src/lib/server/spotify.ts"
click node_db "https://github.com/poppa/mtrek/blob/develop/src/lib/server/db/index.ts"
click node_schema "https://github.com/poppa/mtrek/blob/develop/src/lib/server/db/schema.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_home,node_trek,node_invite,node_round,node_year,node_rankings,node_year_ranking,node_profile,node_user_rankings toneBlue
class node_trek_service,node_ranking_logic toneAmber
class node_auth,node_session,node_spotify_route,node_spotify,node_spotify_api toneMint
class node_db,node_schema toneRose
class node_participant,node_oauth toneIndigo
```

## Components

### Web workflows

- [Trek home](https://github.com/poppa/mtrek/blob/develop/src/routes/%2Bpage.server.ts): `src/routes/+page.server.ts`
- [Trek workspace](https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/%2Bpage.server.ts): `src/routes/treks/[trekId]/+page.server.ts`
- [Invite and join](https://github.com/poppa/mtrek/blob/develop/src/routes/join/%5BinviteCode%5D/%2Bpage.server.ts): `src/routes/join/[inviteCode]/+page.server.ts`
- [Round history](https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/rounds/%5BroundId%5D/%2Bpage.server.ts): `src/routes/treks/[trekId]/rounds/[roundId]/+page.server.ts`
- [Year exploration](https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/years/%5Byear%5D/%2Bpage.server.ts): `src/routes/treks/[trekId]/years/[year]/+page.server.ts`
- [Trek rankings](https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/album-ranking/%2Bpage.server.ts): `src/routes/treks/[trekId]/album-ranking/+page.server.ts`
- [Year rankings](https://github.com/poppa/mtrek/blob/develop/src/routes/treks/%5BtrekId%5D/year-ranking/%2Bpage.server.ts): `src/routes/treks/[trekId]/year-ranking/+page.server.ts`
- [User profile](https://github.com/poppa/mtrek/blob/develop/src/routes/user/%5BuserId%5D/%2Bpage.server.ts): `src/routes/user/[userId]/+page.server.ts`
- [User rankings](https://github.com/poppa/mtrek/blob/develop/src/routes/user/%5BuserId%5D/album-ranking/%2Bpage.server.ts): `src/routes/user/[userId]/album-ranking/+page.server.ts`

### Trek domain

- [Trek service](https://github.com/poppa/mtrek/blob/develop/src/lib/server/trek-service.ts): `src/lib/server/trek-service.ts`
- [Ranking logic](https://github.com/poppa/mtrek/blob/develop/src/lib/ranking.ts): `src/lib/ranking.ts`

### Identity and search

- [Authentication](https://github.com/poppa/mtrek/blob/develop/src/auth.ts): `src/auth.ts`
- [Session helpers](https://github.com/poppa/mtrek/blob/develop/src/lib/server/session.ts): `src/lib/server/session.ts`
- [Album search route](https://github.com/poppa/mtrek/blob/develop/src/routes/api/spotify/search/%2Bserver.ts): `src/routes/api/spotify/search/+server.ts`
- [Spotify client](https://github.com/poppa/mtrek/blob/develop/src/lib/server/spotify.ts): `src/lib/server/spotify.ts`

### Persistence

- [PostgreSQL](https://github.com/poppa/mtrek/blob/develop/src/lib/server/db/index.ts): `src/lib/server/db/index.ts`
- [Database schema](https://github.com/poppa/mtrek/blob/develop/src/lib/server/db/schema.ts): `src/lib/server/db/schema.ts`

### Other components

- **Participant**
- **OAuth providers**
- **Spotify Web API**

## Connections

- Participant → Trek home: uses
- Participant → Trek workspace: manages rounds
- Participant → Invite and join: joins Trek
- Participant → Trek rankings: views
- Participant → User profile: views
- Trek home → Session helpers: requires identity
- Trek home → Trek service: creates and lists
- Trek workspace → Session helpers: checks access
- Trek workspace → Trek service: loads and updates
- Invite and join → Trek service: looks up and joins
- Year exploration → Trek service: loads year
- Round history → Trek service: loads round
- Trek rankings → Trek service: loads albums
- Year rankings → Trek service: loads years
- User profile → Trek service: loads profile data
- User rankings → Trek service: loads user rankings
- Trek service → PostgreSQL: reads and writes
- PostgreSQL → Database schema: implements
- Trek rankings → Ranking logic: uses ranking
- Year rankings → Ranking logic: uses ranking
- Authentication → OAuth providers: authenticates with
- Session helpers → Authentication: reads session
- Album search route → Spotify client: searches albums
- Album search route → Session helpers: checks identity
- Spotify client → Spotify Web API: queries