kunal1218/quadblitz

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.