# trekkateer/usports architecture

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

- Interactive diagram: https://gitdiagram.com/trekkateer/usports
- Repository: https://github.com/trekkateer/usports

## Overview

USports is a campus pickup-sports app: students sign in, discover and filter games, host games, and join or leave them; profiles and push notifications support that workflow. The client manages screens and shared event/profile state, calls the server API, and persists sessions locally. The server routes requests through authentication and domain services to Supabase-backed data access. The README establishes the product capabilities; edges are limited to relationships visible in excerpts or SOURCE INDEX references, so some unsampled screen and notification wiring is omitted.

Main entry points: [`server/src/app.ts`](https://github.com/trekkateer/usports/blob/main/server/src/app.ts) (HTTP application), [`server/src/routes/eventRoutes.ts`](https://github.com/trekkateer/usports/blob/main/server/src/routes/eventRoutes.ts) (Event routes), [`server/src/db/index.ts`](https://github.com/trekkateer/usports/blob/main/server/src/db/index.ts) (Event data access), [`server/src/db/client.ts`](https://github.com/trekkateer/usports/blob/main/server/src/db/client.ts) (Supabase client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_event_screens["Game screens<br/>[index.tsx]"]
  node_event_detail["Game detail<br/>[&#91;id&#93;.tsx]"]
  node_host_screen["Host game<br/>[host.tsx]"]
  node_signin["Sign-in screen<br/>[sign-in.tsx]"]
  node_profile_screen["Profile screen<br/>[profile.tsx]"]
  node_event_context["Event state<br/>[EventContext.tsx]"]
  node_profile_context["Profile state<br/>[ProfileContext.tsx]"]
  node_event_api["Event API<br/>[events.ts]"]
  node_auth_api["Auth API<br/>[auth.ts]"]
  node_profile_api["Profile API<br/>[profile.ts]"]
  node_session[("Session storage<br/>[session.ts]")]
  node_push_client["Push registration"]
end

subgraph group_server["API and domain"]
  node_server_app["HTTP application<br/>[app.ts]"]
  node_event_routes["Event routes<br/>[eventRoutes.ts]"]
  node_auth_routes["Auth routes<br/>[authRoutes.ts]"]
  node_profile_routes["Profile routes<br/>[profileRoutes.ts]"]
  node_push_routes["Push-token routes<br/>[pushTokenRoutes.ts]"]
  node_auth_service["Auth service<br/>[authService.ts]"]
  node_event_service["Event service<br/>[eventService.ts]"]
  node_profile_service["Profile service<br/>[profileService.ts]"]
  node_push_token_service["Push-token service"]
  node_push_service["Push delivery<br/>[pushService.ts]"]
end

subgraph group_data["Persistence and integrations"]
  node_event_repo["Event repository<br/>[eventRepository.ts]"]
  node_db_events["Event data access<br/>[index.ts]"]
  node_db_notifications["Notification data<br/>[notifications.ts]"]
  node_db_client["Supabase client<br/>[client.ts]"]
end

subgraph group_shared["Client utilities"]
  node_filter["Event filters<br/>[filterEvents.ts]"]
end

node_student(("Student"))
node_supabase[("Supabase")]

node_student -->|"browses games"| node_event_screens
node_student -->|"hosts games"| node_host_screen
node_student -->|"signs in"| node_signin
node_student -->|"manages profile"| node_profile_screen
node_event_screens -->|"reads state"| node_event_context
node_event_detail -->|"reads state"| node_event_context
node_event_context -->|"fetches and mutates"| node_event_api
node_event_screens -->|"filters games"| node_filter
node_signin -->|"authenticates"| node_auth_api
node_profile_context -->|"loads and updates"| node_profile_api
node_profile_context -->|"reads and writes"| node_session
node_push_client -->|"uses identity"| node_profile_context
node_push_client -.->|"registers token"| node_push_routes
node_event_api -.->|"HTTP requests"| node_event_routes
node_auth_api -.->|"HTTP requests"| node_auth_routes
node_profile_api -.->|"HTTP requests"| node_profile_routes
node_server_app -->|"mounts routes"| node_event_routes
node_server_app -->|"mounts routes"| node_auth_routes
node_server_app -->|"mounts routes"| node_profile_routes
node_server_app -->|"mounts routes"| node_push_routes
node_event_routes -->|"dispatches operations"| node_event_service
node_event_routes -->|"updates and deletes"| node_event_repo
node_auth_routes -->|"dispatches auth"| node_auth_service
node_profile_routes -->|"dispatches profile"| node_profile_service
node_push_routes -->|"dispatches tokens"| node_push_token_service
node_event_service -->|"uses repository"| node_event_repo
node_event_repo -->|"queries event data"| node_db_events
node_auth_service -->|"uses auth client"| node_db_client
node_auth_service -->|"ensures user row"| node_db_events
node_profile_service -->|"reads and updates profile"| node_db_events
node_push_token_service -->|"stores tokens"| node_db_notifications
node_push_token_service -->|"requests delivery"| node_push_service
node_push_service -->|"uses notifications"| node_db_notifications
node_db_events -->|"queries through"| node_db_client
node_db_notifications -->|"queries through"| node_db_client
node_db_client -->|"connects"| node_supabase

click node_event_screens "https://github.com/trekkateer/usports/blob/main/client/src/app/(tabs)/index.tsx"
click node_event_detail "https://github.com/trekkateer/usports/blob/main/client/src/app/event/%5Bid%5D.tsx"
click node_host_screen "https://github.com/trekkateer/usports/blob/main/client/src/app/host.tsx"
click node_signin "https://github.com/trekkateer/usports/blob/main/client/src/app/sign-in.tsx"
click node_profile_screen "https://github.com/trekkateer/usports/blob/main/client/src/app/(tabs)/profile.tsx"
click node_event_context "https://github.com/trekkateer/usports/blob/main/client/src/context/EventContext.tsx"
click node_profile_context "https://github.com/trekkateer/usports/blob/main/client/src/context/ProfileContext.tsx"
click node_event_api "https://github.com/trekkateer/usports/blob/main/client/src/api/events.ts"
click node_auth_api "https://github.com/trekkateer/usports/blob/main/client/src/api/auth.ts"
click node_profile_api "https://github.com/trekkateer/usports/blob/main/client/src/api/profile.ts"
click node_session "https://github.com/trekkateer/usports/blob/main/client/src/api/session.ts"
click node_push_client "https://github.com/trekkateer/usports/blob/main/client/src/notifications/usePushNotifications.ts"
click node_filter "https://github.com/trekkateer/usports/blob/main/client/src/utils/filterEvents.ts"
click node_server_app "https://github.com/trekkateer/usports/blob/main/server/src/app.ts"
click node_event_routes "https://github.com/trekkateer/usports/blob/main/server/src/routes/eventRoutes.ts"
click node_auth_routes "https://github.com/trekkateer/usports/blob/main/server/src/routes/authRoutes.ts"
click node_profile_routes "https://github.com/trekkateer/usports/blob/main/server/src/routes/profileRoutes.ts"
click node_push_routes "https://github.com/trekkateer/usports/blob/main/server/src/routes/pushTokenRoutes.ts"
click node_auth_service "https://github.com/trekkateer/usports/blob/main/server/src/services/authService.ts"
click node_event_service "https://github.com/trekkateer/usports/blob/main/server/src/services/eventService.ts"
click node_profile_service "https://github.com/trekkateer/usports/blob/main/server/src/services/profileService.ts"
click node_push_token_service "https://github.com/trekkateer/usports/blob/main/server/src/services/pushTokenService.ts"
click node_event_repo "https://github.com/trekkateer/usports/blob/main/server/src/repositories/eventRepository.ts"
click node_db_events "https://github.com/trekkateer/usports/blob/main/server/src/db/index.ts"
click node_db_notifications "https://github.com/trekkateer/usports/blob/main/server/src/db/notifications.ts"
click node_db_client "https://github.com/trekkateer/usports/blob/main/server/src/db/client.ts"
click node_push_service "https://github.com/trekkateer/usports/blob/main/server/src/services/pushService.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_event_screens,node_event_detail,node_host_screen,node_signin,node_profile_screen,node_event_context,node_profile_context,node_event_api,node_auth_api,node_profile_api,node_session,node_push_client toneBlue
class node_server_app,node_event_routes,node_auth_routes,node_profile_routes,node_push_routes,node_auth_service,node_event_service,node_profile_service,node_push_token_service,node_push_service,node_supabase toneAmber
class node_event_repo,node_db_events,node_db_notifications,node_db_client toneMint
class node_filter toneRose
class node_student toneIndigo
```

## Components

### Mobile client

- [Game screens](https://github.com/trekkateer/usports/blob/main/client/src/app/(tabs)/index.tsx): `client/src/app/(tabs)/index.tsx`
- [Game detail](https://github.com/trekkateer/usports/blob/main/client/src/app/event/%5Bid%5D.tsx): `client/src/app/event/[id].tsx`
- [Host game](https://github.com/trekkateer/usports/blob/main/client/src/app/host.tsx): `client/src/app/host.tsx`
- [Sign-in screen](https://github.com/trekkateer/usports/blob/main/client/src/app/sign-in.tsx): `client/src/app/sign-in.tsx`
- [Profile screen](https://github.com/trekkateer/usports/blob/main/client/src/app/(tabs)/profile.tsx): `client/src/app/(tabs)/profile.tsx`
- [Event state](https://github.com/trekkateer/usports/blob/main/client/src/context/EventContext.tsx): `client/src/context/EventContext.tsx`
- [Profile state](https://github.com/trekkateer/usports/blob/main/client/src/context/ProfileContext.tsx): `client/src/context/ProfileContext.tsx`
- [Event API](https://github.com/trekkateer/usports/blob/main/client/src/api/events.ts): `client/src/api/events.ts`
- [Auth API](https://github.com/trekkateer/usports/blob/main/client/src/api/auth.ts): `client/src/api/auth.ts`
- [Profile API](https://github.com/trekkateer/usports/blob/main/client/src/api/profile.ts): `client/src/api/profile.ts`
- [Session storage](https://github.com/trekkateer/usports/blob/main/client/src/api/session.ts): `client/src/api/session.ts`
- [Push registration](https://github.com/trekkateer/usports/blob/main/client/src/notifications/usePushNotifications.ts): `client/src/notifications/usePushNotifications.ts`

### API and domain

- [HTTP application](https://github.com/trekkateer/usports/blob/main/server/src/app.ts): `server/src/app.ts`
- [Event routes](https://github.com/trekkateer/usports/blob/main/server/src/routes/eventRoutes.ts): `server/src/routes/eventRoutes.ts`
- [Auth routes](https://github.com/trekkateer/usports/blob/main/server/src/routes/authRoutes.ts): `server/src/routes/authRoutes.ts`
- [Profile routes](https://github.com/trekkateer/usports/blob/main/server/src/routes/profileRoutes.ts): `server/src/routes/profileRoutes.ts`
- [Push-token routes](https://github.com/trekkateer/usports/blob/main/server/src/routes/pushTokenRoutes.ts): `server/src/routes/pushTokenRoutes.ts`
- [Auth service](https://github.com/trekkateer/usports/blob/main/server/src/services/authService.ts): `server/src/services/authService.ts`
- [Event service](https://github.com/trekkateer/usports/blob/main/server/src/services/eventService.ts): `server/src/services/eventService.ts`
- [Profile service](https://github.com/trekkateer/usports/blob/main/server/src/services/profileService.ts): `server/src/services/profileService.ts`
- [Push-token service](https://github.com/trekkateer/usports/blob/main/server/src/services/pushTokenService.ts): `server/src/services/pushTokenService.ts`
- [Push delivery](https://github.com/trekkateer/usports/blob/main/server/src/services/pushService.ts): `server/src/services/pushService.ts`

### Persistence and integrations

- [Event repository](https://github.com/trekkateer/usports/blob/main/server/src/repositories/eventRepository.ts): `server/src/repositories/eventRepository.ts`
- [Event data access](https://github.com/trekkateer/usports/blob/main/server/src/db/index.ts): `server/src/db/index.ts`
- [Notification data](https://github.com/trekkateer/usports/blob/main/server/src/db/notifications.ts): `server/src/db/notifications.ts`
- [Supabase client](https://github.com/trekkateer/usports/blob/main/server/src/db/client.ts): `server/src/db/client.ts`

### Client utilities

- [Event filters](https://github.com/trekkateer/usports/blob/main/client/src/utils/filterEvents.ts): `client/src/utils/filterEvents.ts`

### Other components

- **Student**
- **Supabase**

## Connections

- Student → Game screens: browses games
- Student → Host game: hosts games
- Student → Sign-in screen: signs in
- Student → Profile screen: manages profile
- Game screens → Event state: reads state (evidence: `client/src/app/(tabs)/index.tsx`)
- Game detail → Event state: reads state (evidence: `client/src/app/event/[id].tsx`)
- Event state → Event API: fetches and mutates (evidence: `client/src/context/EventContext.tsx`)
- Game screens → Event filters: filters games (evidence: `client/src/app/(tabs)/index.tsx`)
- Sign-in screen → Auth API: authenticates (evidence: `client/src/app/sign-in.tsx`)
- Profile state → Profile API: loads and updates (evidence: `client/src/context/ProfileContext.tsx`)
- Profile state → Session storage: reads and writes (evidence: `client/src/context/ProfileContext.tsx`)
- Push registration → Profile state: uses identity (evidence: `client/src/notifications/usePushNotifications.ts`)
- Push registration → Push-token routes: registers token
- Event API → Event routes: HTTP requests
- Auth API → Auth routes: HTTP requests
- Profile API → Profile routes: HTTP requests
- HTTP application → Event routes: mounts routes (evidence: `server/src/app.ts`)
- HTTP application → Auth routes: mounts routes (evidence: `server/src/app.ts`)
- HTTP application → Profile routes: mounts routes (evidence: `server/src/app.ts`)
- HTTP application → Push-token routes: mounts routes (evidence: `server/src/app.ts`)
- Event routes → Event service: dispatches operations (evidence: `server/src/routes/eventRoutes.ts`)
- Event routes → Event repository: updates and deletes (evidence: `server/src/routes/eventRoutes.ts`)
- Auth routes → Auth service: dispatches auth (evidence: `server/src/routes/authRoutes.ts`)
- Profile routes → Profile service: dispatches profile (evidence: `server/src/routes/profileRoutes.ts`)
- Push-token routes → Push-token service: dispatches tokens (evidence: `server/src/routes/pushTokenRoutes.ts`)
- Event service → Event repository: uses repository (evidence: `server/src/services/eventService.ts`)
- Event repository → Event data access: queries event data (evidence: `server/src/repositories/eventRepository.ts`)
- Auth service → Supabase client: uses auth client (evidence: `server/src/services/authService.ts`)
- Auth service → Event data access: ensures user row (evidence: `server/src/services/authService.ts`)
- Profile service → Event data access: reads and updates profile (evidence: `server/src/services/profileService.ts`)
- Push-token service → Notification data: stores tokens (evidence: `server/src/services/pushTokenService.ts`)
- Push-token service → Push delivery: requests delivery (evidence: `server/src/services/pushTokenService.ts`)
- Push delivery → Notification data: uses notifications (evidence: `server/src/services/pushService.ts`)
- Event data access → Supabase client: queries through (evidence: `server/src/db/index.ts`)
- Notification data → Supabase client: queries through (evidence: `server/src/db/notifications.ts`)
- Supabase client → Supabase: connects (evidence: `server/src/db/client.ts`)
