# upendradungana/sportsfb architecture

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

- Interactive diagram: https://gitdiagram.com/upendradungana/sportsfb
- Repository: https://github.com/upendradungana/sportsfb

## Overview

SportsFB is a Bhutan-focused sports-facility booking product for players, facility owners, and administrators. Players discover facilities and reserve slots, then pay and submit proof; owners manage listings, approve requests, and verify payments. Admins verify owners and facilities, review plan payments, manage users, and handle feedback. Authentication, role/MFA guards, and shared booking logic form key internal layers. The README documents the product branches; sampled sources show selected API, persistence, notification, and booking relationships, so unsampled links are omitted or marked unverified.

Main entry points: [`src/db/schema.ts`](https://github.com/upendradungana/sportsfb/blob/main/src/db/schema.ts) (Neon Postgres), [`src/lib/booking.ts`](https://github.com/upendradungana/sportsfb/blob/main/src/lib/booking.ts) (Booking lifecycle), [`src/lib/notify.ts`](https://github.com/upendradungana/sportsfb/blob/main/src/lib/notify.ts) (Notification service), [`src/auth.ts`](https://github.com/upendradungana/sportsfb/blob/main/src/auth.ts) (Google sign-in)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_auth["Google sign-in<br/>[auth.ts]"]
  node_guards["Role and MFA guards<br/>[guard.ts]"]
  node_totp["Authenticator MFA<br/>[totp.ts]"]
  node_onboarding["Profile onboarding<br/>[route.ts]"]
  node_profile["Account controls<br/>[route.ts]"]
end

subgraph group_player["Player booking"]
  node_facility_discovery["Facility discovery<br/>[route.ts]"]
  node_map["Map display<br/>[MapView.tsx]"]
  node_booking_api["Booking endpoints<br/>[route.ts]"]
  node_booking_logic["Booking lifecycle<br/>[booking.ts]"]
  node_payment_proof["Payment proof<br/>[route.ts]"]
  node_booking_receipts["Booking receipts<br/>[route.ts]"]
  node_booking_expiry["Booking expiry hook<br/>[route.ts]"]
end

subgraph group_owner["Owner operations"]
  node_owner_facilities["Facility management<br/>[route.ts]"]
  node_availability["Availability and blocks<br/>[route.ts]"]
  node_plans["Owner plans<br/>[route.ts]"]
  node_subscriptions["Subscription rules<br/>[subscriptions.ts]"]
end

subgraph group_admin["Administration"]
  node_admin_ops["Admin review and actions<br/>[route.ts]"]
  node_admin_data["Admin data<br/>[route.ts]"]
  node_admin_totp["Admin MFA setup<br/>[route.ts]"]
  node_feedback["Feedback<br/>[route.ts]"]
  node_notifications["Notifications<br/>[route.ts]"]
  node_notify["Notification service<br/>[notify.ts]"]
end

node_players(("Players"))
node_owners(("Facility owners"))
node_admins(("Administrators"))
node_database[("Neon Postgres<br/>[schema.ts]")]
node_qstash["QStash timers"]

node_players -->|"sign in"| node_auth
node_owners -->|"sign in"| node_auth
node_admins -->|"sign in"| node_auth
node_auth -->|"reads and writes"| node_database
node_auth -->|"provides session"| node_guards
node_guards -->|"checks MFA"| node_totp
node_admins -->|"enroll MFA"| node_admin_totp
node_admin_totp -->|"verifies codes"| node_totp
node_admin_totp -->|"stores MFA state"| node_database
node_players -->|"set up profile"| node_onboarding
node_onboarding -->|"updates user"| node_database
node_players -->|"find facilities"| node_facility_discovery
node_facility_discovery -->|"searches facilities"| node_database
node_facility_discovery -->|"alerts on listing"| node_notify
node_map -.->|"shows locations"| node_players
node_players -->|"reserve slots"| node_booking_api
node_booking_api -.->|"dispatches booking"| node_booking_logic
node_booking_logic -->|"updates bookings"| node_database
node_booking_logic -->|"sends booking alerts"| node_notify
node_booking_logic -->|"schedules expiry"| node_qstash
node_players -->|"upload proof"| node_payment_proof
node_payment_proof -->|"submits proof"| node_booking_logic
node_owners -->|"view receipts"| node_booking_receipts
node_booking_receipts -->|"loads receipt"| node_booking_logic
node_booking_expiry -->|"expires booking"| node_booking_logic
node_owners -->|"manage listings"| node_owner_facilities
node_owner_facilities -->|"manages facilities"| node_database
node_owner_facilities -->|"requests review"| node_notify
node_owners -->|"set blocked times"| node_availability
node_availability -->|"stores blocks"| node_database
node_owners -->|"pay for plan"| node_plans
node_plans -->|"stores subscription"| node_database
node_plans -->|"requests payment review"| node_notify
node_subscriptions -->|"reads subscriptions"| node_database
node_admins -->|"review and manage"| node_admin_ops
node_admin_ops -->|"updates records"| node_database
node_admin_ops -->|"sends updates"| node_notify
node_admins -->|"review queues"| node_admin_data
node_admin_data -->|"reads records"| node_database
node_players -->|"send feedback"| node_feedback
node_feedback -->|"stores feedback"| node_database
node_feedback -->|"alerts admins"| node_notify
node_players -.->|"view alerts"| node_notifications
node_notifications -->|"reads and marks read"| node_database
node_notify -->|"writes notifications"| node_database

click node_auth "https://github.com/upendradungana/sportsfb/blob/main/src/auth.ts"
click node_guards "https://github.com/upendradungana/sportsfb/blob/main/src/lib/guard.ts"
click node_totp "https://github.com/upendradungana/sportsfb/blob/main/src/lib/totp.ts"
click node_onboarding "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/onboarding/route.ts"
click node_profile "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/me/route.ts"
click node_facility_discovery "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/facilities/route.ts"
click node_map "https://github.com/upendradungana/sportsfb/blob/main/src/components/MapView.tsx"
click node_booking_api "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/bookings/reserve/route.ts"
click node_booking_logic "https://github.com/upendradungana/sportsfb/blob/main/src/lib/booking.ts"
click node_payment_proof "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/payments/upload-proof/route.ts"
click node_booking_receipts "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/receipts/%5BbookingId%5D/route.ts"
click node_booking_expiry "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/webhooks/expire-booking/route.ts"
click node_owner_facilities "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/owner/facilities/route.ts"
click node_availability "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/owner/blocks/route.ts"
click node_plans "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/owner/plan/route.ts"
click node_subscriptions "https://github.com/upendradungana/sportsfb/blob/main/src/lib/subscriptions.ts"
click node_admin_ops "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/admin/action/route.ts"
click node_admin_data "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/admin/data/route.ts"
click node_admin_totp "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/admin/totp/route.ts"
click node_feedback "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/feedback/route.ts"
click node_notifications "https://github.com/upendradungana/sportsfb/blob/main/src/app/api/notifications/route.ts"
click node_notify "https://github.com/upendradungana/sportsfb/blob/main/src/lib/notify.ts"
click node_database "https://github.com/upendradungana/sportsfb/blob/main/src/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_auth,node_guards,node_totp,node_onboarding,node_profile toneBlue
class node_facility_discovery,node_map,node_booking_api,node_booking_logic,node_payment_proof,node_booking_receipts,node_booking_expiry,node_database toneAmber
class node_owner_facilities,node_availability,node_plans,node_subscriptions toneMint
class node_admin_ops,node_admin_data,node_admin_totp,node_feedback,node_notifications,node_notify toneRose
class node_players,node_owners,node_admins,node_qstash toneIndigo
```

## Components

### Identity and access

- [Google sign-in](https://github.com/upendradungana/sportsfb/blob/main/src/auth.ts): `src/auth.ts`
- [Role and MFA guards](https://github.com/upendradungana/sportsfb/blob/main/src/lib/guard.ts): `src/lib/guard.ts`
- [Authenticator MFA](https://github.com/upendradungana/sportsfb/blob/main/src/lib/totp.ts): `src/lib/totp.ts`
- [Profile onboarding](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/onboarding/route.ts): `src/app/api/onboarding/route.ts`
- [Account controls](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/me/route.ts): `src/app/api/me/route.ts`

### Player booking

- [Facility discovery](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/facilities/route.ts): `src/app/api/facilities/route.ts`
- [Map display](https://github.com/upendradungana/sportsfb/blob/main/src/components/MapView.tsx): `src/components/MapView.tsx`
- [Booking endpoints](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/bookings/reserve/route.ts): `src/app/api/bookings/reserve/route.ts`
- [Booking lifecycle](https://github.com/upendradungana/sportsfb/blob/main/src/lib/booking.ts): `src/lib/booking.ts`
- [Payment proof](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/payments/upload-proof/route.ts): `src/app/api/payments/upload-proof/route.ts`
- [Booking receipts](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/receipts/%5BbookingId%5D/route.ts): `src/app/api/receipts/[bookingId]/route.ts`
- [Booking expiry hook](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/webhooks/expire-booking/route.ts): `src/app/api/webhooks/expire-booking/route.ts`

### Owner operations

- [Facility management](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/owner/facilities/route.ts): `src/app/api/owner/facilities/route.ts`
- [Availability and blocks](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/owner/blocks/route.ts): `src/app/api/owner/blocks/route.ts`
- [Owner plans](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/owner/plan/route.ts): `src/app/api/owner/plan/route.ts`
- [Subscription rules](https://github.com/upendradungana/sportsfb/blob/main/src/lib/subscriptions.ts): `src/lib/subscriptions.ts`

### Administration

- [Admin review and actions](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/admin/action/route.ts): `src/app/api/admin/action/route.ts`
- [Admin data](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/admin/data/route.ts): `src/app/api/admin/data/route.ts`
- [Admin MFA setup](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/admin/totp/route.ts): `src/app/api/admin/totp/route.ts`
- [Feedback](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/feedback/route.ts): `src/app/api/feedback/route.ts`
- [Notifications](https://github.com/upendradungana/sportsfb/blob/main/src/app/api/notifications/route.ts): `src/app/api/notifications/route.ts`
- [Notification service](https://github.com/upendradungana/sportsfb/blob/main/src/lib/notify.ts): `src/lib/notify.ts`

### Other components

- **Players**
- **Facility owners**
- **Administrators**
- [Neon Postgres](https://github.com/upendradungana/sportsfb/blob/main/src/db/schema.ts): `src/db/schema.ts`
- **QStash timers**

## Connections

- Players → Google sign-in: sign in
- Facility owners → Google sign-in: sign in
- Administrators → Google sign-in: sign in
- Google sign-in → Neon Postgres: reads and writes (evidence: `src/auth.ts`)
- Google sign-in → Role and MFA guards: provides session (evidence: `src/lib/guard.ts`)
- Role and MFA guards → Authenticator MFA: checks MFA (evidence: `src/lib/guard.ts`)
- Administrators → Admin MFA setup: enroll MFA (evidence: `src/app/api/admin/totp/route.ts`)
- Admin MFA setup → Authenticator MFA: verifies codes (evidence: `src/app/api/admin/totp/route.ts`)
- Admin MFA setup → Neon Postgres: stores MFA state (evidence: `src/app/api/admin/totp/route.ts`)
- Players → Profile onboarding: set up profile (evidence: `src/app/api/onboarding/route.ts`)
- Profile onboarding → Neon Postgres: updates user (evidence: `src/app/api/onboarding/route.ts`)
- Players → Facility discovery: find facilities
- Facility discovery → Neon Postgres: searches facilities (evidence: `src/app/api/facilities/route.ts`)
- Facility discovery → Notification service: alerts on listing (evidence: `src/app/api/facilities/route.ts`)
- Map display → Players: shows locations
- Players → Booking endpoints: reserve slots
- Booking endpoints → Booking lifecycle: dispatches booking
- Booking lifecycle → Neon Postgres: updates bookings (evidence: `src/lib/booking.ts`)
- Booking lifecycle → Notification service: sends booking alerts (evidence: `src/lib/booking.ts`)
- Booking lifecycle → QStash timers: schedules expiry (evidence: `src/lib/booking.ts`)
- Players → Payment proof: upload proof
- Payment proof → Booking lifecycle: submits proof (evidence: `src/app/api/payments/upload-proof/route.ts`)
- Facility owners → Booking receipts: view receipts
- Booking receipts → Booking lifecycle: loads receipt (evidence: `src/app/api/receipts/[bookingId]/route.ts`)
- Booking expiry hook → Booking lifecycle: expires booking (evidence: `src/app/api/webhooks/expire-booking/route.ts`)
- Facility owners → Facility management: manage listings
- Facility management → Neon Postgres: manages facilities (evidence: `src/app/api/owner/facilities/route.ts`)
- Facility management → Notification service: requests review (evidence: `src/app/api/owner/facilities/route.ts`)
- Facility owners → Availability and blocks: set blocked times
- Availability and blocks → Neon Postgres: stores blocks (evidence: `src/app/api/owner/blocks/route.ts`)
- Facility owners → Owner plans: pay for plan
- Owner plans → Neon Postgres: stores subscription (evidence: `src/app/api/owner/plan/route.ts`)
- Owner plans → Notification service: requests payment review (evidence: `src/app/api/owner/plan/route.ts`)
- Subscription rules → Neon Postgres: reads subscriptions (evidence: `src/lib/subscriptions.ts`)
- Administrators → Admin review and actions: review and manage
- Admin review and actions → Neon Postgres: updates records (evidence: `src/app/api/admin/action/route.ts`)
- Admin review and actions → Notification service: sends updates (evidence: `src/app/api/admin/action/route.ts`)
- Administrators → Admin data: review queues
- Admin data → Neon Postgres: reads records (evidence: `src/app/api/admin/data/route.ts`)
- Players → Feedback: send feedback
- Feedback → Neon Postgres: stores feedback (evidence: `src/app/api/feedback/route.ts`)
- Feedback → Notification service: alerts admins (evidence: `src/app/api/feedback/route.ts`)
- Players → Notifications: view alerts
- Notifications → Neon Postgres: reads and marks read (evidence: `src/app/api/notifications/route.ts`)
- Notification service → Neon Postgres: writes notifications (evidence: `src/lib/notify.ts`)