# green14712-byte/tripquest-server architecture

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

- Interactive diagram: https://gitdiagram.com/green14712-byte/tripquest-server
- Repository: https://github.com/green14712-byte/tripquest-server

## Overview

This is a NestJS backend for challenge-based missions, with user, institution, and administrator capabilities. The main participant workflow is to authenticate, discover an active challenge and its missions, then submit mission verification (location and/or QR) and manage completion photos. Institutions manage challenges, missions, and applications; administrators manage users. The graph reflects sampled calls and SOURCE INDEX references; unsampled modules are included as capability nodes, but their internal behavior and uncertain links are not inferred.

Main entry points: [`src/app.module.ts`](https://github.com/green14712-byte/tripquest-server/blob/main/src/app.module.ts) (Nest app composition), [`src/prisma/db.ts`](https://github.com/green14712-byte/tripquest-server/blob/main/src/prisma/db.ts) (ORM client), [`src/storage/supabase-storage.ts`](https://github.com/green14712-byte/tripquest-server/blob/main/src/storage/supabase-storage.ts) (Supabase storage), [`src/missions/missions.service.ts`](https://github.com/green14712-byte/tripquest-server/blob/main/src/missions/missions.service.ts) (Mission management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and identity"]
  node_auth_api["Auth endpoints<br/>[auth.controller.ts]"]
  node_auth_logic["Identity and admin<br/>[auth.service.ts]"]
  node_jwt["JWT guard<br/>[jwt-auth.guard.ts]"]
  node_roles["Role guard<br/>[roles.guard.ts]"]
  node_role_metadata["Role metadata<br/>[roles.decorator.ts]"]
  node_mail["Email delivery<br/>[mail.service.ts]"]
end

subgraph group_challenge["Challenges and institutions"]
  node_challenges_api["Challenge endpoints"]
  node_challenge_logic["Challenge management"]
  node_challenge_time["Operating state"]
  node_applications_api["Institution applications"]
  node_applications_logic["Application processing"]
  node_institutions_api["Institution endpoints"]
  node_institutions_logic["Institution queries"]
end

subgraph group_mission["Missions and participation"]
  node_missions_api["Mission endpoints"]
  node_mission_logic["Mission management"]
  node_qr_crypto["QR token crypto"]
  node_participation_api["Participation endpoints"]
  node_participation_logic["Challenge participation"]
  node_completion_api["Completion endpoints"]
  node_completion_logic["Mission verification"]
end

subgraph group_infra["Persistence and integrations"]
  node_database[("Postgres database")]
  node_db_client["ORM client<br/>[db.ts]"]
  node_file_storage["Supabase storage"]
  node_app["Nest app composition<br/>[app.module.ts]"]
  node_entry["HTTP bootstrap<br/>[main.ts]"]
end

node_client(("API clients"))
node_supabase[("Supabase service")]

node_client -->|"authenticates"| node_auth_api
node_client -->|"browses"| node_challenges_api
node_client -->|"manages missions"| node_missions_api
node_client -->|"participates"| node_participation_api
node_client -->|"verifies mission"| node_completion_api
node_client -->|"applies"| node_applications_api
node_auth_api -->|"calls"| node_auth_logic
node_auth_logic -->|"reads and writes"| node_db_client
node_auth_logic -->|"sends email"| node_mail
node_jwt -->|"loads user"| node_db_client
node_roles -->|"reads roles"| node_role_metadata
node_challenges_api -->|"calls"| node_challenge_logic
node_challenge_logic -->|"reads and writes"| node_db_client
node_challenge_logic -->|"checks operation time"| node_challenge_time
node_challenges_api -->|"uploads cover"| node_file_storage
node_applications_api -->|"calls"| node_applications_logic
node_applications_logic -->|"reads and writes"| node_db_client
node_applications_logic -->|"stores evidence"| node_file_storage
node_institutions_api -->|"calls"| node_institutions_logic
node_institutions_logic -->|"queries"| node_db_client
node_missions_api -->|"calls"| node_mission_logic
node_mission_logic -->|"reads and writes"| node_db_client
node_mission_logic -->|"manages photos"| node_file_storage
node_mission_logic -->|"uses"| node_qr_crypto
node_participation_api -->|"calls"| node_participation_logic
node_participation_logic -->|"reads and writes"| node_db_client
node_participation_logic -->|"checks operation time"| node_challenge_time
node_completion_api -->|"calls"| node_completion_logic
node_completion_logic -->|"reads and writes"| node_db_client
node_completion_logic -->|"checks operation time"| node_challenge_time
node_completion_logic -->|"manages completion photos"| node_file_storage
node_file_storage -->|"uploads files"| node_supabase
node_db_client -->|"connects"| node_database
node_entry -->|"bootstraps"| node_app
node_app -->|"registers module"| node_auth_api
node_app -->|"registers module"| node_challenges_api
node_app -->|"registers module"| node_missions_api
node_app -->|"registers module"| node_participation_api
node_app -->|"registers module"| node_completion_api
node_app -->|"registers module"| node_applications_api
node_app -->|"registers module"| node_institutions_api

click node_auth_api "https://github.com/green14712-byte/tripquest-server/blob/main/src/auth/auth.controller.ts"
click node_auth_logic "https://github.com/green14712-byte/tripquest-server/blob/main/src/auth/auth.service.ts"
click node_jwt "https://github.com/green14712-byte/tripquest-server/blob/main/src/auth/jwt-auth.guard.ts"
click node_roles "https://github.com/green14712-byte/tripquest-server/blob/main/src/auth/roles.guard.ts"
click node_role_metadata "https://github.com/green14712-byte/tripquest-server/blob/main/src/auth/roles.decorator.ts"
click node_mail "https://github.com/green14712-byte/tripquest-server/blob/main/src/mail/mail.service.ts"
click node_challenges_api "https://github.com/green14712-byte/tripquest-server/blob/main/src/challenges/challenges.controller.ts"
click node_challenge_logic "https://github.com/green14712-byte/tripquest-server/blob/main/src/challenges/challenges.service.ts"
click node_challenge_time "https://github.com/green14712-byte/tripquest-server/blob/main/src/challenges/challenge-operation-time.ts"
click node_applications_api "https://github.com/green14712-byte/tripquest-server/blob/main/src/institution-applications/institution-applications.controller.ts"
click node_applications_logic "https://github.com/green14712-byte/tripquest-server/blob/main/src/institution-applications/institution-applications.service.ts"
click node_institutions_api "https://github.com/green14712-byte/tripquest-server/blob/main/src/institutions/institutions.controller.ts"
click node_institutions_logic "https://github.com/green14712-byte/tripquest-server/blob/main/src/institutions/institutions.service.ts"
click node_missions_api "https://github.com/green14712-byte/tripquest-server/blob/main/src/missions/missions.controller.ts"
click node_mission_logic "https://github.com/green14712-byte/tripquest-server/blob/main/src/missions/missions.service.ts"
click node_qr_crypto "https://github.com/green14712-byte/tripquest-server/blob/main/src/missions/mission-qr-crypto.ts"
click node_participation_api "https://github.com/green14712-byte/tripquest-server/blob/main/src/challenge-participations/challenge-participations.controller.ts"
click node_participation_logic "https://github.com/green14712-byte/tripquest-server/blob/main/src/challenge-participations/challenge-participations.service.ts"
click node_completion_api "https://github.com/green14712-byte/tripquest-server/blob/main/src/mission-completions/mission-completions.controller.ts"
click node_completion_logic "https://github.com/green14712-byte/tripquest-server/blob/main/src/mission-completions/mission-completions.service.ts"
click node_db_client "https://github.com/green14712-byte/tripquest-server/blob/main/src/prisma/db.ts"
click node_file_storage "https://github.com/green14712-byte/tripquest-server/blob/main/src/storage/supabase-storage.ts"
click node_app "https://github.com/green14712-byte/tripquest-server/blob/main/src/app.module.ts"
click node_entry "https://github.com/green14712-byte/tripquest-server/blob/main/src/main.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_auth_api,node_auth_logic,node_jwt,node_roles,node_role_metadata,node_mail,node_client toneBlue
class node_challenges_api,node_challenge_logic,node_challenge_time,node_applications_api,node_applications_logic,node_institutions_api,node_institutions_logic,node_supabase toneAmber
class node_missions_api,node_mission_logic,node_qr_crypto,node_participation_api,node_participation_logic,node_completion_api,node_completion_logic toneMint
class node_database,node_db_client,node_file_storage,node_app,node_entry toneRose
```

## Components

### Access and identity

- [Auth endpoints](https://github.com/green14712-byte/tripquest-server/blob/main/src/auth/auth.controller.ts): `src/auth/auth.controller.ts`
- [Identity and admin](https://github.com/green14712-byte/tripquest-server/blob/main/src/auth/auth.service.ts): `src/auth/auth.service.ts`
- [JWT guard](https://github.com/green14712-byte/tripquest-server/blob/main/src/auth/jwt-auth.guard.ts): `src/auth/jwt-auth.guard.ts`
- [Role guard](https://github.com/green14712-byte/tripquest-server/blob/main/src/auth/roles.guard.ts): `src/auth/roles.guard.ts`
- [Role metadata](https://github.com/green14712-byte/tripquest-server/blob/main/src/auth/roles.decorator.ts): `src/auth/roles.decorator.ts`
- [Email delivery](https://github.com/green14712-byte/tripquest-server/blob/main/src/mail/mail.service.ts): `src/mail/mail.service.ts`

### Challenges and institutions

- [Challenge endpoints](https://github.com/green14712-byte/tripquest-server/blob/main/src/challenges/challenges.controller.ts): `src/challenges/challenges.controller.ts`
- [Challenge management](https://github.com/green14712-byte/tripquest-server/blob/main/src/challenges/challenges.service.ts): `src/challenges/challenges.service.ts`
- [Operating state](https://github.com/green14712-byte/tripquest-server/blob/main/src/challenges/challenge-operation-time.ts): `src/challenges/challenge-operation-time.ts`
- [Institution applications](https://github.com/green14712-byte/tripquest-server/blob/main/src/institution-applications/institution-applications.controller.ts): `src/institution-applications/institution-applications.controller.ts`
- [Application processing](https://github.com/green14712-byte/tripquest-server/blob/main/src/institution-applications/institution-applications.service.ts): `src/institution-applications/institution-applications.service.ts`
- [Institution endpoints](https://github.com/green14712-byte/tripquest-server/blob/main/src/institutions/institutions.controller.ts): `src/institutions/institutions.controller.ts`
- [Institution queries](https://github.com/green14712-byte/tripquest-server/blob/main/src/institutions/institutions.service.ts): `src/institutions/institutions.service.ts`

### Missions and participation

- [Mission endpoints](https://github.com/green14712-byte/tripquest-server/blob/main/src/missions/missions.controller.ts): `src/missions/missions.controller.ts`
- [Mission management](https://github.com/green14712-byte/tripquest-server/blob/main/src/missions/missions.service.ts): `src/missions/missions.service.ts`
- [QR token crypto](https://github.com/green14712-byte/tripquest-server/blob/main/src/missions/mission-qr-crypto.ts): `src/missions/mission-qr-crypto.ts`
- [Participation endpoints](https://github.com/green14712-byte/tripquest-server/blob/main/src/challenge-participations/challenge-participations.controller.ts): `src/challenge-participations/challenge-participations.controller.ts`
- [Challenge participation](https://github.com/green14712-byte/tripquest-server/blob/main/src/challenge-participations/challenge-participations.service.ts): `src/challenge-participations/challenge-participations.service.ts`
- [Completion endpoints](https://github.com/green14712-byte/tripquest-server/blob/main/src/mission-completions/mission-completions.controller.ts): `src/mission-completions/mission-completions.controller.ts`
- [Mission verification](https://github.com/green14712-byte/tripquest-server/blob/main/src/mission-completions/mission-completions.service.ts): `src/mission-completions/mission-completions.service.ts`

### Persistence and integrations

- **Postgres database**
- [ORM client](https://github.com/green14712-byte/tripquest-server/blob/main/src/prisma/db.ts): `src/prisma/db.ts`
- [Supabase storage](https://github.com/green14712-byte/tripquest-server/blob/main/src/storage/supabase-storage.ts): `src/storage/supabase-storage.ts`
- [Nest app composition](https://github.com/green14712-byte/tripquest-server/blob/main/src/app.module.ts): `src/app.module.ts`
- [HTTP bootstrap](https://github.com/green14712-byte/tripquest-server/blob/main/src/main.ts): `src/main.ts`

### Other components

- **API clients**
- **Supabase service**

## Connections

- API clients → Auth endpoints: authenticates (evidence: `src/auth/auth.controller.ts`)
- API clients → Challenge endpoints: browses (evidence: `src/challenges/challenges.controller.ts`)
- API clients → Mission endpoints: manages missions (evidence: `src/missions/missions.controller.ts`)
- API clients → Participation endpoints: participates (evidence: `src/challenge-participations/challenge-participations.controller.ts`)
- API clients → Completion endpoints: verifies mission (evidence: `src/mission-completions/mission-completions.controller.ts`)
- API clients → Institution applications: applies (evidence: `src/institution-applications/institution-applications.controller.ts`)
- Auth endpoints → Identity and admin: calls (evidence: `src/auth/auth.controller.ts`)
- Identity and admin → ORM client: reads and writes (evidence: `src/auth/auth.service.ts`)
- Identity and admin → Email delivery: sends email (evidence: `src/auth/auth.service.ts`)
- JWT guard → ORM client: loads user (evidence: `src/auth/jwt-auth.guard.ts`)
- Role guard → Role metadata: reads roles (evidence: `src/auth/roles.guard.ts`)
- Challenge endpoints → Challenge management: calls (evidence: `src/challenges/challenges.controller.ts`)
- Challenge management → ORM client: reads and writes (evidence: `src/challenges/challenges.service.ts`)
- Challenge management → Operating state: checks operation time (evidence: `src/challenges/challenges.service.ts`)
- Challenge endpoints → Supabase storage: uploads cover (evidence: `src/challenges/challenges.controller.ts`)
- Institution applications → Application processing: calls (evidence: `src/institution-applications/institution-applications.controller.ts`)
- Application processing → ORM client: reads and writes (evidence: `src/institution-applications/institution-applications.service.ts`)
- Application processing → Supabase storage: stores evidence (evidence: `src/institution-applications/institution-applications.service.ts`)
- Institution endpoints → Institution queries: calls (evidence: `src/institutions/institutions.controller.ts`)
- Institution queries → ORM client: queries (evidence: `src/institutions/institutions.service.ts`)
- Mission endpoints → Mission management: calls (evidence: `src/missions/missions.controller.ts`)
- Mission management → ORM client: reads and writes (evidence: `src/missions/missions.service.ts`)
- Mission management → Supabase storage: manages photos (evidence: `src/missions/missions.service.ts`)
- Mission management → QR token crypto: uses (evidence: `src/missions/missions.service.ts`)
- Participation endpoints → Challenge participation: calls (evidence: `src/challenge-participations/challenge-participations.controller.ts`)
- Challenge participation → ORM client: reads and writes (evidence: `src/challenge-participations/challenge-participations.service.ts`)
- Challenge participation → Operating state: checks operation time (evidence: `src/challenge-participations/challenge-participations.service.ts`)
- Completion endpoints → Mission verification: calls (evidence: `src/mission-completions/mission-completions.controller.ts`)
- Mission verification → ORM client: reads and writes (evidence: `src/mission-completions/mission-completions.service.ts`)
- Mission verification → Operating state: checks operation time (evidence: `src/mission-completions/mission-completions.service.ts`)
- Mission verification → Supabase storage: manages completion photos (evidence: `src/mission-completions/mission-completions.service.ts`)
- Supabase storage → Supabase service: uploads files (evidence: `src/storage/supabase-storage.ts`)
- ORM client → Postgres database: connects (evidence: `src/prisma/db.ts`)
- HTTP bootstrap → Nest app composition: bootstraps (evidence: `src/main.ts`)
- Nest app composition → Auth endpoints: registers module (evidence: `src/app.module.ts`)
- Nest app composition → Challenge endpoints: registers module (evidence: `src/app.module.ts`)
- Nest app composition → Mission endpoints: registers module (evidence: `src/app.module.ts`)
- Nest app composition → Participation endpoints: registers module (evidence: `src/app.module.ts`)
- Nest app composition → Completion endpoints: registers module (evidence: `src/app.module.ts`)
- Nest app composition → Institution applications: registers module (evidence: `src/app.module.ts`)
- Nest app composition → Institution endpoints: registers module (evidence: `src/app.module.ts`)
