ah-muzahid/codearena

1. Overall shape

- This repository is a single Next.js application plus supporting execution infrastructure for a competitive programming platform.

- The main product surface lives in src/app, while backend behavior is split across App Router API routes, domain services/controllers, background workers, Redis, MongoDB, Socket.io, and Docker-based sandboxes.

2. Frontend/application shell

- The user-facing app is built with Next.js App Router and React.

- Route groups cover the major product areas: landing/home, problems, contests, leaderboard, profile, feed, interview, admin, docs, and auth.

- Most screens are composed from feature modules under src/features/*, with shared UI and layout primitives in src/components and src/shared.

3. Backend entrypoint: API routes

- The architectural backend boundary is src/app/api/**/route.js.

- These route handlers expose all core capabilities: authentication, problem browsing/solving, submissions, leaderboards, contests, interview sessions, social feed, notifications, stats, admin operations, and execution/evaluation.

- Route handlers delegate to controllers/services rather than embedding domain logic directly.

4. Domain layer

- Core business logic is organized in:

- src/controllers for request-oriented orchestration

- src/services for reusable domain workflows

- src/middlewares for auth, rate limiting, and role checks

- This separation matters because the same domain concepts are reused by web pages, API routes, workers, and sockets.

5. Persistence layer

- The primary data store is MongoDB, with models under src/models.

- Major persisted domains include users, problems, submissions, contests, contest participants, leaderboards, posts, reactions, notifications, interview sessions/messages/snapshots, logs, stats history, and test cases.

- There is also a Redis layer used for caching, queues, rate limiting, and transient realtime/session state.

6. Code execution and judging pipeline

- Code execution is isolated from the main web app.

- Language-specific Docker executors live under docker/executors with separate images and runner scripts for C++, Java, JavaScript, and Python, plus a seccomp profile for sandbox hardening.

- The API layer sends execution/evaluation work into a queue and/or execution service, and the result is then persisted and pushed back to the user.

- This is the critical trust boundary: untrusted user code never runs in the Next.js process.

7. Background workers and async processing

- Long-running or high-throughput tasks are handled out of band via worker scripts and service workers in src/services/*.worker.js and scripts/*.

- Likely worker responsibilities include submission judging, plagiarism checks, stats updates, AI processing, leaderboard maintenance, cache warming, and notification workflows.

- Redis is the coordination point for these asynchronous pipelines.

8. Realtime communication

- The app uses Socket.io for realtime features, with namespaces under src/socket/namespaces.

- Realtime is used especially for interview sessions, live contest/arena updates, and submission status updates.

- WebSocket authentication is explicitly supported through src/lib/ws-token.js, src/lib/socket-auth.js, and the /api/auth/ws-token route.

9. Interview subsystem

- Interview mode is a distinct product area with its own pages, context, hooks, socket flows, and services.

- It includes session lifecycle management, replay/rehydration/export, AI-driven conversation flow, voice input, execution during interview, and snapshot/history persistence.

- The subsystem combines MongoDB-backed session records with realtime sockets and AI workers, making it one of the most stateful parts of the app.

10. AI integration

- AI is used beyond marketing language: there are dedicated clients and prompts in src/lib/ai, src/prompts, and interview-focused worker/services.

- The AI path appears to power interview coaching, feedback, summarization, and evaluation rather than being a generic chat feature.

- This creates a separate external dependency boundary for model/API calls.

11. Contest, leaderboard, and problem-solving flows

- Competitive programming is a first-class domain:

- problems, tags, submissions, reactions, and problem status in the solving flow

- contests, registration, participation, live/final leaderboards, and results

- global leaderboard and ranking/statistics views

- The UI for these is split into dedicated feature modules, but all funnel through shared problem/submission/contest services and Mongo models.

12. Social, notifications, and personalization

- The platform includes a feed, posts, comments, likes, follows/friends, push notifications, and user recommendations.

- These features create cross-cutting data flow from user actions into stored social activity, notification generation, and personalized suggestions.

- There is also browser-side push support via the service worker in public/sw.js and notification hooks/providers.

13. Admin and operations surface

- src/app/admin and src/app/api/admin expose operational controls for contests, problems, users, metrics, logs, plagiarism, and interview moderation/flags.

- This is a separate privileged boundary guarded by role middleware and intended for system maintenance and moderation rather than end-user workflows.

14. Infrastructure and deployment

- The repo is designed for containerized deployment with Dockerfile, docker-compose.yml, docker-compose.dev.yml, Railway/Render configs, Redis config, and execution-service support.

- The architecture assumes a Node.js runtime for the web app, MongoDB for durable state, Redis for coordination, Docker for sandboxing, and Socket.io/AI services for realtime and intelligent features.