# kunal1218/quadblitz architecture

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

- Interactive diagram: https://gitdiagram.com/kunal1218/quadblitz
- Repository: https://github.com/kunal1218/quadblitz

## Overview

#### Purpose and Topology
QuadBlitz is a campus-focused social platform for finding friends, collaborators, and cofounders. It is a TypeScript monorepo with three clients/services: Next.js web, Express API, and Expo mobile; shared contracts live in `packages/shared/src/index.ts` and `packages/shared/src/types.ts`.

#### Entrypoints and Clients
- The web application uses the Next.js App Router, rooted at `apps/web/app/layout.tsx` and `apps/web/app/page.tsx`. Route segments expose social, clubs, map, marketplace, messaging, profiles, and administration.
- The mobile Expo application starts through `apps/mobile/index.ts` and `apps/mobile/App.tsx`, with tab-oriented screens under `apps/mobile/src/screens/tabs/`.
- The API process starts at `apps/api/src/index.ts`; its route composition boundary is `apps/api/src/routes/index.ts`.

#### API Layering and Domain Modules
The Express backend follows routes → controllers → services → persistence/integrations. Representative boundaries are `apps/api/src/routes/marketplaceRoutes.ts`, `apps/api/src/controllers/marketplaceController.ts`, and `apps/api/src/services/marketplaceService.ts`. Domain modules cover authentication, feed/posts, friends, clubs, events/map, challenges, profiles, requests, notifications, direct/club chat, and marketplace conversations.

#### Identity, Session, and State Boundaries
Authentication is handled across `apps/api/src/controllers/authController.ts` and `apps/api/src/services/authService.ts`. User records are intended for PostgreSQL, while sessions are stored in Redis, accessed via `apps/api/src/db/index.ts` and `apps/api/src/db/redis.ts`. Web auth state is client-facing through `apps/web/features/auth/AuthProvider.tsx`; mobile API/session access is centralized in `apps/mobile/src/api/client.ts`.

#### Social Discovery Flow
Web pages and feature modules render campus activity, groups, friendship, requests, profiles, and discovery. The home feed is composed in `apps/web/features/home/HomeDashboard.tsx`; club views originate at `apps/web/app/clubs/page.tsx`; map discovery is organized around `apps/web/features/map/MapDiscoveryPage.tsx`. These clients call API endpoints, which delegate domain reads/writes to services; some provider data remains deliberately stubbed/mock-backed.

#### Real-Time and Communications
Chat, direct messages, club chat, notifications, and marketplace conversations are backend domains with a socket integration boundary in `apps/api/src/services/socketService.ts`. The web socket client is `apps/web/lib/socket.ts`; message routes include `apps/web/app/messages/[handle]/page.tsx` and marketplace-specific conversation pages under `apps/web/app/marketplace/messages/`.

#### Marketplace, Events, and Challenges
Marketplace supports listings, images, and buyer/seller conversations, with schema migrations in `apps/api/src/db/migrations/20260209_create_listings_table.sql` and `apps/api/src/db/migrations/20260210_create_marketplace_conversations.sql`. Map/events APIs are represented by `apps/api/src/services/mapService.ts` and `apps/api/src/services/eventsService.ts`; web maps use Mapbox through `apps/web/features/map/MapCanvas.tsx`. Challenges include attempt management and an AI judging boundary at `apps/api/src/services/geminiJudgeService.ts`.

#### Runtime and Infrastructure
Web deploys to Vercel; API, PostgreSQL, and Redis are intended for Railway. API configuration expects `DATABASE_URL` and `REDIS_URL`; browser/mobile clients use public API-base environment variables. Mapbox is an external browser-map dependency, and Gemini is an external challenge-evaluation integration. File upload handling is isolated at `apps/api/src/middleware/upload.ts`.

Main entry points: [`apps/web/app/layout.tsx`](https://github.com/kunal1218/quadblitz/blob/main/apps/web/app/layout.tsx) (Next.js web app), [`apps/api/src/index.ts`](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/index.ts) (API process), [`apps/api/src/services/marketplaceService.ts`](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/services/marketplaceService.ts) (Domain services), [`apps/api/src/routes/index.ts`](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/routes/index.ts) (Route composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_web["Next.js web app<br/>Next.js client<br/>[layout.tsx]"]
  node_web_home["Home dashboard<br/>web feature<br/>[HomeDashboard.tsx]"]
  node_web_auth["Web auth state<br/>React provider<br/>[AuthProvider.tsx]"]
  node_web_map["Map discovery<br/>web feature"]
  node_web_socket["Web socket client<br/>[socket.ts]"]
  node_mobile["Expo mobile app<br/>Expo client<br/>[App.tsx]"]
  node_mobile_client["Mobile API client<br/>API/session client<br/>[client.ts]"]
end

subgraph group_api["Express API"]
  node_api_entry["API process<br/>Express server<br/>[index.ts]"]
  node_routes["Route composition<br/>Express routes<br/>[index.ts]"]
  node_controllers["Controllers"]
  node_services["Domain services<br/>service layer"]
  node_auth["Authentication<br/>auth service<br/>[authService.ts]"]
  node_sockets["Socket integration<br/>realtime service<br/>[socketService.ts]"]
  node_uploads["Upload handling<br/>Express middleware<br/>[upload.ts]"]
end

subgraph group_data["Data &amp; integrations"]
  node_postgres[("PostgreSQL<br/>primary database<br/>[index.ts]")]
  node_redis[("Redis<br/>session store<br/>[redis.ts]")]
  node_mapbox{{"Mapbox<br/>map provider<br/>[MapCanvas.tsx]"}}
  node_gemini{{"Gemini judge<br/>AI integration"}}
end

subgraph group_platform["Deployment"]
  node_vercel{{"Vercel<br/>web hosting"}}
  node_railway{{"Railway<br/>API and data hosting"}}
end

node_shared["Shared contracts<br/>TypeScript contracts<br/>[index.ts]"]

node_web -->|"renders"| node_web_home
node_web -->|"uses"| node_web_auth
node_web -->|"renders"| node_web_map
node_web -->|"connects"| node_web_socket
node_mobile -->|"uses"| node_mobile_client
node_web -->|"HTTPS API"| node_api_entry
node_mobile_client -->|"HTTPS API"| node_api_entry
node_web_socket -->|"real-time connection"| node_sockets
node_api_entry -->|"mounts"| node_routes
node_routes -->|"dispatches"| node_controllers
node_controllers -->|"invokes"| node_services
node_controllers -->|"auth endpoints"| node_auth
node_services -->|"persists domain data"| node_postgres
node_auth -->|"user records"| node_postgres
node_auth -->|"sessions"| node_redis
node_services -->|"publishes events"| node_sockets
node_routes -->|"upload routes"| node_uploads
node_web_map -->|"renders maps"| node_mapbox
node_services -->|"judges challenges"| node_gemini
node_web -.->|"uses contracts"| node_shared
node_mobile -.->|"uses contracts"| node_shared
node_api_entry -.->|"uses contracts"| node_shared
node_vercel -->|"hosts"| node_web
node_railway -->|"hosts"| node_api_entry
node_railway -->|"hosts"| node_postgres
node_railway -->|"hosts"| node_redis

click node_web "https://github.com/kunal1218/quadblitz/blob/main/apps/web/app/layout.tsx"
click node_web_home "https://github.com/kunal1218/quadblitz/blob/main/apps/web/features/home/HomeDashboard.tsx"
click node_web_auth "https://github.com/kunal1218/quadblitz/blob/main/apps/web/features/auth/AuthProvider.tsx"
click node_web_map "https://github.com/kunal1218/quadblitz/blob/main/apps/web/features/map/MapDiscoveryPage.tsx"
click node_web_socket "https://github.com/kunal1218/quadblitz/blob/main/apps/web/lib/socket.ts"
click node_mobile "https://github.com/kunal1218/quadblitz/blob/main/apps/mobile/App.tsx"
click node_mobile_client "https://github.com/kunal1218/quadblitz/blob/main/apps/mobile/src/api/client.ts"
click node_shared "https://github.com/kunal1218/quadblitz/blob/main/packages/shared/src/index.ts"
click node_api_entry "https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/index.ts"
click node_routes "https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/routes/index.ts"
click node_controllers "https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/controllers/marketplaceController.ts"
click node_services "https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/services/marketplaceService.ts"
click node_auth "https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/services/authService.ts"
click node_sockets "https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/services/socketService.ts"
click node_uploads "https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/middleware/upload.ts"
click node_postgres "https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/db/index.ts"
click node_redis "https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/db/redis.ts"
click node_mapbox "https://github.com/kunal1218/quadblitz/blob/main/apps/web/features/map/MapCanvas.tsx"
click node_gemini "https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/services/geminiJudgeService.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_web_home,node_web_auth,node_web_map,node_web_socket,node_mobile,node_mobile_client toneBlue
class node_api_entry,node_routes,node_controllers,node_services,node_auth,node_sockets,node_uploads toneAmber
class node_postgres,node_redis,node_mapbox,node_gemini toneMint
class node_vercel,node_railway toneRose
class node_shared toneNeutral
```

## Components

### Clients

- [Next.js web app](https://github.com/kunal1218/quadblitz/blob/main/apps/web/app/layout.tsx): Next.js client · Social, clubs, map, marketplace, messaging, profiles, and admin UI. · `apps/web/app/layout.tsx`
- [Home dashboard](https://github.com/kunal1218/quadblitz/blob/main/apps/web/features/home/HomeDashboard.tsx): web feature · Composes the campus activity feed. · `apps/web/features/home/HomeDashboard.tsx`
- [Web auth state](https://github.com/kunal1218/quadblitz/blob/main/apps/web/features/auth/AuthProvider.tsx): React provider · `apps/web/features/auth/AuthProvider.tsx`
- [Map discovery](https://github.com/kunal1218/quadblitz/blob/main/apps/web/features/map/MapDiscoveryPage.tsx): web feature · `apps/web/features/map/MapDiscoveryPage.tsx`
- [Web socket client](https://github.com/kunal1218/quadblitz/blob/main/apps/web/lib/socket.ts): socket client · `apps/web/lib/socket.ts`
- [Expo mobile app](https://github.com/kunal1218/quadblitz/blob/main/apps/mobile/App.tsx): Expo client · Tab-oriented mobile experience. · `apps/mobile/App.tsx`
- [Mobile API client](https://github.com/kunal1218/quadblitz/blob/main/apps/mobile/src/api/client.ts): API/session client · `apps/mobile/src/api/client.ts`

### Express API

- [API process](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/index.ts): Express server · `apps/api/src/index.ts`
- [Route composition](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/routes/index.ts): Express routes · Composes domain endpoint modules. · `apps/api/src/routes/index.ts`
- [Controllers](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/controllers/marketplaceController.ts): HTTP controllers · Translate requests into domain operations. · `apps/api/src/controllers/marketplaceController.ts`
- [Domain services](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/services/marketplaceService.ts): service layer · Auth, social, clubs, events, chat, notifications, marketplace, and challenges. · `apps/api/src/services/marketplaceService.ts`
- [Authentication](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/services/authService.ts): auth service · Identity and session lifecycle. · `apps/api/src/services/authService.ts`
- [Socket integration](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/services/socketService.ts): realtime service · Supports chat, notifications, and conversations. · `apps/api/src/services/socketService.ts`
- [Upload handling](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/middleware/upload.ts): Express middleware · Isolated file upload boundary for marketplace images. · `apps/api/src/middleware/upload.ts`

### Data & integrations

- [PostgreSQL](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/db/index.ts): primary database · User and domain records, including marketplace listings and conversations. · `apps/api/src/db/index.ts`
- [Redis](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/db/redis.ts): session store · `apps/api/src/db/redis.ts`
- [Mapbox](https://github.com/kunal1218/quadblitz/blob/main/apps/web/features/map/MapCanvas.tsx): map provider · `apps/web/features/map/MapCanvas.tsx`
- [Gemini judge](https://github.com/kunal1218/quadblitz/blob/main/apps/api/src/services/geminiJudgeService.ts): AI integration · Evaluates challenge attempts. · `apps/api/src/services/geminiJudgeService.ts`

### Deployment

- **Vercel**: web hosting
- **Railway**: API and data hosting

### Other components

- [Shared contracts](https://github.com/kunal1218/quadblitz/blob/main/packages/shared/src/index.ts): TypeScript contracts · Shared types and API contracts for all runtimes. · `packages/shared/src/index.ts`

## Connections

- Next.js web app → Home dashboard: renders
- Next.js web app → Web auth state: uses
- Next.js web app → Map discovery: renders
- Next.js web app → Web socket client: connects
- Expo mobile app → Mobile API client: uses
- Next.js web app → API process: HTTPS API
- Mobile API client → API process: HTTPS API
- Web socket client → Socket integration: real-time connection
- API process → Route composition: mounts
- Route composition → Controllers: dispatches
- Controllers → Domain services: invokes
- Controllers → Authentication: auth endpoints
- Domain services → PostgreSQL: persists domain data
- Authentication → PostgreSQL: user records
- Authentication → Redis: sessions
- Domain services → Socket integration: publishes events
- Route composition → Upload handling: upload routes
- Map discovery → Mapbox: renders maps
- Domain services → Gemini judge: judges challenges
- Next.js web app → Shared contracts: uses contracts
- Expo mobile app → Shared contracts: uses contracts
- API process → Shared contracts: uses contracts
- Vercel → Next.js web app: hosts
- Railway → API process: hosts
- Railway → PostgreSQL: hosts
- Railway → Redis: hosts