Internal Code Contracts

Contracts must stay in sync with implementation. If route behavior, context state, emitted/listened socket events, or component props change, update these docs in the same PR.

Frontend + context modules

Module	File	Contract
App shell and provider composition	src/pages/_app.tsx	Pages, Frontend Context Providers
Home + onboarding pages	src/pages/index.tsx, src/pages/tutorial.tsx	Pages
Auth pages	src/pages/login.tsx, src/pages/signup.tsx	Pages
Matchmaking flow	src/pages/matchmaking.tsx, src/components/home/FindLobbySection.tsx, src/components/home/DifficultySection.tsx	Pages, UI Components
Game room flow	src/pages/game/[gameID].tsx	Pages
Results flow	src/pages/results/[gameID].tsx, src/hooks/useGameResults.ts	Pages
Socket lifecycle	src/contexts/SocketContext.tsx	Frontend Context Providers
Party + friend lifecycle	src/contexts/PartyContext.tsx, src/contexts/FriendshipContext.tsx	Frontend Context Providers
Matchmaking shared state	src/contexts/MatchmakingContext.tsx	Frontend Context Providers
Game-local shared state	src/contexts/GameStateContext.tsx, src/contexts/GameTestCasesContext.tsx	Frontend Context Providers
Navbar + side panel	src/components/Navbar.tsx, src/components/sidebar/*	UI Components
Game-room components	src/components/ProblemBox.tsx, src/components/ChatBox.tsx, src/components/GameTimer.tsx, src/components/gameTests/*	UI Components
Results components	src/components/Analysisbox.tsx, src/components/TestCaseResultsBox.tsx	UI Components

Shared backend modules

Module	File	Contract
auth	./src/lib/auth.ts	auth / authClient
authClient	./src/lib/auth-client.ts	auth / authClient
prisma	./src/lib/prisma.ts	Prisma Client
proxy	./src/proxy.ts	Middleware
sockets	./server/index.js	Websockets
execution	./server/sockets/handlers/executionHandlers.js	Execution

Error-handling conventions

• API handlers should return typed error payloads with status codes (4xx/5xx) instead of crashing the process.
• UI-level errors are surfaced through notification helpers (e.g., showErrorNotification) or local page-state messaging.
• Unauthenticated access is guarded both by middleware/proxy rules and by page-level session checks.