# codeforgeai-io/codeforge-ai architecture

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

- Interactive diagram: https://gitdiagram.com/codeforgeai-io/codeforge-ai
- Repository: https://github.com/codeforgeai-io/codeforge-ai

## Overview

#### Purpose and Runtime
CodeForge AI is a single full-stack coding-interview preparation platform: problem solving, code execution, frontend challenges, AI mentoring, contests, learning plans, community, billing, and administration. It runs as a Next.js 15 App Router application with React 19 and TypeScript, deployable to Vercel.
- Entrypoints: `src/app/layout.tsx`, `src/app/page.tsx`, `src/middleware.ts`
- Public, authenticated platform, and admin route surfaces are separated under `src/app/`, notably `src/app/(platform)/layout.tsx` and `src/app/admin/layout.tsx`.

#### Request Boundary, Auth, and API
Middleware is the first security boundary: session gating, public-route access, origin/CORS checks for mutations, and security headers. Route handlers implement the HTTP API; handlers should remain orchestration layers over schemas, auth/rate-limit utilities, and services.
- `src/middleware.ts`
- `src/app/api/auth/me/route.ts`
- `src/lib/api-auth.ts`
- `src/lib/rate-limit.ts`

Auth is Supabase-based with email/password, OAuth, and WebAuthn passkeys. Auth callback and passkey flows are explicit API endpoints.
- `src/lib/supabase/server.ts`
- `src/lib/webauthn.ts`
- `src/app/api/auth/passkey/register/verify/route.ts`

#### Product UI and Client State
The App Router pages compose feature modules into three major experiences: public marketing/content, the authenticated learning workspace, and back-office administration. Shared providers and navigation establish application-wide client concerns; workspace-local state uses Zustand.
- `src/app/(platform)/dashboard/page.tsx`
- `src/components/providers.tsx`
- `src/features/workspace/workspace.tsx`
- `src/store/workspace.ts`

#### Domain Services and Persistence
Business logic resides in `src/services`, decoupling API/UI from persistence and provider implementations. Supabase Postgres is the primary data system, modeled by SQL migrations and TypeScript models; Supabase Storage handles user and career uploads. `data-backend` preserves a module-selectable Mongo rollback path.
- `src/services/questions.ts`
- `src/services/submissions.ts`
- `src/lib/data-backend.ts`
- `supabase/migrations/0001_init_core.sql`
- `src/models/User.ts`

Core persisted domains include users/profiles, questions, submissions/progress, contests, discussions, subscriptions, AI usage, and spaced repetition.

#### Coding Execution Pipeline
DSA workspace and standalone compiler submit source, language, and stdin to server APIs. The execution service selects Paiza, Judge0, or self-hosted Piston at runtime, normalizes results, and lets submission flows persist outcomes and gamification effects.
- `src/app/api/execute/route.ts`
- `src/app/api/compiler/route.ts`
- `src/services/execution/index.ts`
- `src/services/execution/normalize.ts`
- `src/services/execution/paiza.ts`

This is an important external-trust boundary: code never executes in the Next.js process; it is delegated to configured execution providers.

#### AI, Learning, and Engagement Flows
AI routes accept workspace/tool context and delegate prompt orchestration and streaming model access to the AI service. Usage/credits and feature access constrain paid or metered capabilities. Learning outcomes feed analytics, weakness detection, revision, badges, and activity tracking.
- `src/app/api/ai/chat/route.ts`
- `src/services/ai/groq.ts`
- `src/services/ai-credits.ts`
- `src/services/gamification/index.ts`
- `src/services/roadmaps.ts`

Groq is the primary LLM integration; missing credentials should disable only AI capabilities.

#### Commerce, Operations, and External Infrastructure
Razorpay subscription handlers manage order, verification, cancellation, and webhooks; billing state is stored behind dedicated services. Admin pages and APIs operate content, users, submissions, prompts, campaigns, and reporting. Redis/Upstash supports rate limiting and hot leaderboard caching, with fallback behavior. PostHog and OpenTelemetry provide product analytics and observability.
- `src/app/api/subscription/webhook/route.ts`
- `src/lib/razorpay.ts`
- `src/services/billing-store.ts`
- `src/app/api/admin/analytics/route.ts`
- `src/lib/redis.ts`
- `src/instrumentation.ts`

Main entry points: [`src/app/api/auth/me/route.ts`](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/app/api/auth/me/route.ts) (API route handlers), [`src/lib/data-backend.ts`](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/data-backend.ts) (Data backend selector), [`src/app/layout.tsx`](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/app/layout.tsx) (App entrypoints), [`src/middleware.ts`](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/middleware.ts) (Security middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Next.js Runtime"]
  node_entrypoints["App entrypoints<br/>Next.js App Router<br/>[layout.tsx]"]
  node_middleware{{"Security middleware<br/>request boundary<br/>[middleware.ts]"}}
  node_route_api["API route handlers<br/>HTTP orchestration<br/>[route.ts]"]
end

subgraph group_product["Product Experiences"]
  node_platform["Learning workspace<br/>authenticated UI<br/>[layout.tsx]"]
  node_workspace_ui["DSA workspace<br/>feature module<br/>[workspace.tsx]"]
  node_workspace_store["Workspace state<br/>Zustand store<br/>[workspace.ts]"]
  node_admin["Admin operations<br/>admin UI and API<br/>[layout.tsx]"]
end

subgraph group_services["Domain Services"]
  node_auth{{"Supabase auth<br/>identity service<br/>[server.ts]"}}
  node_api_security["API auth &amp; rate limits<br/>request utility<br/>[api-auth.ts]"]
  node_execution{{"Execution service<br/>code execution broker<br/>[index.ts]"}}
  node_ai["AI service<br/>LLM orchestration<br/>[groq.ts]"]
  node_learning["Learning &amp; engagement<br/>domain services<br/>[index.ts]"]
  node_billing["Billing service<br/>subscription domain<br/>[billing-store.ts]"]
end

subgraph group_data["Data &amp; Infrastructure"]
  node_data_access["Data backend selector<br/>persistence abstraction<br/>[data-backend.ts]"]
  node_postgres[("Supabase Postgres<br/>primary database<br/>[0001_init_core.sql]")]
  node_storage[("Supabase Storage<br/>object storage")]
  node_redis[("Redis / Upstash<br/>cache and rate limits<br/>[redis.ts]")]
  node_telemetry["Analytics &amp; telemetry<br/>observability<br/>[instrumentation.ts]"]
end

subgraph group_external["External Providers"]
  node_providers{{"Execution providers<br/>remote code runners<br/>[paiza.ts]"}}
  node_groq{{"Groq<br/>LLM provider"}}
  node_razorpay{{"Razorpay<br/>payment provider<br/>[razorpay.ts]"}}
end

node_entrypoints -->|"incoming requests"| node_middleware
node_middleware -->|"authorized pages"| node_platform
node_middleware -->|"protected API"| node_route_api
node_entrypoints -->|"admin routes"| node_admin
node_platform -->|"composes"| node_workspace_ui
node_workspace_ui -->|"local state"| node_workspace_store
node_route_api -->|"auth and limits"| node_api_security
node_api_security -->|"validates session"| node_auth
node_route_api -->|"execute and compile"| node_execution
node_execution -->|"delegates untrusted code"| node_providers
node_route_api -->|"AI chat"| node_ai
node_ai -->|"streams model access"| node_groq
node_route_api -->|"subscription webhooks"| node_billing
node_billing -->|"orders and verification"| node_razorpay
node_route_api -->|"learning outcomes"| node_learning
node_platform -->|"reads product data"| node_data_access
node_learning -->|"persists progress"| node_data_access
node_billing -->|"persists billing state"| node_data_access
node_data_access -->|"primary persistence"| node_postgres
node_data_access -->|"uploads"| node_storage
node_api_security -->|"rate-limit counters"| node_redis
node_learning -.->|"leaderboard cache"| node_redis
node_entrypoints -.->|"instrumented runtime"| node_telemetry
node_admin -->|"admin APIs"| node_route_api

click node_entrypoints "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/app/layout.tsx"
click node_middleware "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/middleware.ts"
click node_route_api "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/app/api/auth/me/route.ts"
click node_platform "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/app/(platform)/layout.tsx"
click node_workspace_ui "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/features/workspace/workspace.tsx"
click node_workspace_store "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/store/workspace.ts"
click node_admin "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/app/admin/layout.tsx"
click node_auth "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/supabase/server.ts"
click node_api_security "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/api-auth.ts"
click node_execution "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/services/execution/index.ts"
click node_ai "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/services/ai/groq.ts"
click node_learning "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/services/gamification/index.ts"
click node_billing "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/services/billing-store.ts"
click node_data_access "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/data-backend.ts"
click node_postgres "https://github.com/codeforgeai-io/codeforge-ai/blob/main/supabase/migrations/0001_init_core.sql"
click node_redis "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/redis.ts"
click node_providers "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/services/execution/paiza.ts"
click node_razorpay "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/razorpay.ts"
click node_telemetry "https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/instrumentation.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_entrypoints,node_middleware,node_route_api toneBlue
class node_platform,node_workspace_ui,node_workspace_store,node_admin toneAmber
class node_auth,node_api_security,node_execution,node_ai,node_learning,node_billing toneMint
class node_data_access,node_postgres,node_storage,node_redis,node_telemetry toneRose
class node_providers,node_groq,node_razorpay toneIndigo
```

## Components

### Next.js Runtime

- [App entrypoints](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/app/layout.tsx): Next.js App Router · Root layout and public entry surface. · `src/app/layout.tsx`
- [Security middleware](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/middleware.ts): request boundary · Gates sessions, mutations, origins, and headers. · `src/middleware.ts`
- [API route handlers](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/app/api/auth/me/route.ts): HTTP orchestration · Routes delegate auth, validation, and domain work. · `src/app/api/auth/me/route.ts`

### Product Experiences

- [Learning workspace](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/app/(platform)/layout.tsx): authenticated UI · Platform layout and dashboard experience. · `src/app/(platform)/layout.tsx`
- [DSA workspace](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/features/workspace/workspace.tsx): feature module · `src/features/workspace/workspace.tsx`
- [Workspace state](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/store/workspace.ts): Zustand store · `src/store/workspace.ts`
- [Admin operations](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/app/admin/layout.tsx): admin UI and API · Content, users, reporting, and operations. · `src/app/admin/layout.tsx`

### Domain Services

- [Supabase auth](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/supabase/server.ts): identity service · Email, OAuth, and passkey authentication. · `src/lib/supabase/server.ts`
- [API auth & rate limits](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/api-auth.ts): request utility · `src/lib/api-auth.ts`
- [Execution service](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/services/execution/index.ts): code execution broker · Selects and normalizes remote execution providers. · `src/services/execution/index.ts`
- [AI service](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/services/ai/groq.ts): LLM orchestration · Streams contextual mentoring and tool responses. · `src/services/ai/groq.ts`
- [Learning & engagement](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/services/gamification/index.ts): domain services · Roadmaps, gamification, revision, and progress outcomes. · `src/services/gamification/index.ts`
- [Billing service](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/services/billing-store.ts): subscription domain · `src/services/billing-store.ts`

### Data & Infrastructure

- [Data backend selector](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/data-backend.ts): persistence abstraction · Supports Supabase primary storage and Mongo rollback. · `src/lib/data-backend.ts`
- [Supabase Postgres](https://github.com/codeforgeai-io/codeforge-ai/blob/main/supabase/migrations/0001_init_core.sql): primary database · Core product domains and billing state. · `supabase/migrations/0001_init_core.sql`
- **Supabase Storage**: object storage · User and career uploads.
- [Redis / Upstash](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/redis.ts): cache and rate limits · Caches leaderboards with fallback behavior. · `src/lib/redis.ts`
- [Analytics & telemetry](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/instrumentation.ts): observability · PostHog product analytics and OpenTelemetry instrumentation. · `src/instrumentation.ts`

### External Providers

- [Execution providers](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/services/execution/paiza.ts): remote code runners · Paiza, Judge0, or self-hosted Piston execute untrusted code. · `src/services/execution/paiza.ts`
- **Groq**: LLM provider · AI is disabled without credentials.
- [Razorpay](https://github.com/codeforgeai-io/codeforge-ai/blob/main/src/lib/razorpay.ts): payment provider · `src/lib/razorpay.ts`

## Connections

- App entrypoints → Security middleware: incoming requests
- Security middleware → Learning workspace: authorized pages
- Security middleware → API route handlers: protected API
- App entrypoints → Admin operations: admin routes
- Learning workspace → DSA workspace: composes
- DSA workspace → Workspace state: local state
- API route handlers → API auth & rate limits: auth and limits
- API auth & rate limits → Supabase auth: validates session
- API route handlers → Execution service: execute and compile
- Execution service → Execution providers: delegates untrusted code
- API route handlers → AI service: AI chat
- AI service → Groq: streams model access
- API route handlers → Billing service: subscription webhooks
- Billing service → Razorpay: orders and verification
- API route handlers → Learning & engagement: learning outcomes
- Learning workspace → Data backend selector: reads product data
- Learning & engagement → Data backend selector: persists progress
- Billing service → Data backend selector: persists billing state
- Data backend selector → Supabase Postgres: primary persistence
- Data backend selector → Supabase Storage: uploads
- API auth & rate limits → Redis / Upstash: rate-limit counters
- Learning & engagement → Redis / Upstash: leaderboard cache
- App entrypoints → Analytics & telemetry: instrumented runtime
- Admin operations → API route handlers: admin APIs