# vickykumarofficial/arcade-learn architecture

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

- Interactive diagram: https://gitdiagram.com/vickykumarofficial/arcade-learn
- Repository: https://github.com/vickykumarofficial/arcade-learn

## Overview

1. **Top-level shape**
   - This repository is a multi-part learning platform, not a single app.
   - The main production path is a **React + TypeScript SPA** in `src/`, a **Node.js backend API** in `backend/`, and a **separate job-scraping subsystem** in `job-scraper/`.
   - The deployed app appears to be hosted on **Render**, with static/frontend build config also present for **Vercel**.

2. **Frontend: browser-based product shell**
   - `src/` is the user-facing application built with **Vite, React 18, TypeScript, and Tailwind CSS**.
   - `src/main.tsx` and `src/App.tsx` anchor routing and app bootstrap.
   - The frontend is organized around **pages** (`src/pages/`) and **shared UI components** (`src/components/`), with heavy reuse of `shadcn/ui`-style primitives under `src/components/ui/`.

3. **Frontend feature domains**
   - The UI is split into distinct product areas:
     - **Learning roadmaps**: roadmap listings, roadmap detail flows, and roadmap-specific interactive pages.
     - **Gamification**: dashboard, achievements, activity heatmap, leaderboard, ratings.
     - **Career tools**: career recommendations, jobs, salary/career cards.
     - **Resume tools**: resume upload, parsing, builder, preview, PDF viewing.
     - **AI tools**: AI chat, doubt solving, AI roadmap generation.
     - **Coding practice**: problem browser, code editor, execution panel, stats dashboard.
   - This separation matters because each area has its own data and service layer rather than being one generic content app.

4. **State management and client-side boundaries**
   - Shared application state is managed with **React Context** in `src/contexts/` for auth, survey/onboarding, resume building, and gamified test state.
   - Custom hooks in `src/hooks/` wrap recurring behaviors like auth timeout, mobile detection, toast handling, and career recommendation logic.
   - Client-side business logic also lives in `src/lib/`, especially for **gamification, ratings, roadmap progress, and career matching**.

5. **Frontend data and content model**
   - A large amount of learning content is **compiled into the frontend** under `src/data/`.
   - This includes roadmap definitions, node details, coding problems, FAQs, testimonials, and career metadata.
   - That means the app is partly content-driven: the browser reads structured static datasets to render learning paths and quizzes, not just server-fetched records.

6. **Frontend service layer**
   - `src/services/` is the boundary between the SPA and external systems.
   - It includes services for:
     - AI chat and roadmap generation
     - quiz/test scoring
     - resume parsing and resume CRUD
     - progress tracking
     - activity logging
     - code execution
     - email notifications
   - The code is organized so UI components do not talk directly to backend or third-party APIs; they go through these service modules.

7. **Execution isolation in the browser**
   - `src/workers/` contains web workers for JavaScript/TypeScript and Python execution.
   - This is an important architectural boundary: coding-practice execution happens off the main UI thread, which keeps the app responsive and isolates untrusted user code from the primary React runtime.

8. **Backend API: server-side orchestration**
   - `backend/` is a **Node.js backend** that acts as the server-side integration layer.
   - `backend/server.js` is the central API entrypoint.
   - Backend services cover the non-UI business capabilities: analytics, certificates, email delivery, job recommendation, PDF generation, resume processing, subscriptions, surveys, activity tracking, and progress persistence.

9. **Backend data and persistence**
   - The backend uses a database layer in `backend/lib/db.js` and a Supabase admin client in `backend/lib/supabase.js`.
   - SQL schema files in `backend/database/` and the repo-level `database/` directory indicate the platform relies on a **Postgres-backed Supabase database** with schema migrations for resumes, surveys, jobs, activity tracking, and scoring.
   - The local `data/resumes/` folder shows an additional file-based storage path for resume artifacts or parsed resume snapshots.

10. **AI integration boundary**
   - AI features are backend-mediated, with `backend/services/openRouterProvider.js` and migration/check scripts for OpenRouter.
   - The README explicitly says AI model calls are **backend-only**, which keeps model credentials off the client and centralizes prompt/orchestration logic.
   - Related backend services like roadmap doubt solving and AI orchestration likely fan out to OpenRouter from the server side rather than from the SPA.

11. **Job data pipeline**
   - Job discovery is split into two pieces:
     - `backend/fetch-adzuna-jobs.js` and `backend/fetch-remoteok-jobs.js` fetch from external job APIs.
     - `job-scraper/` is a separate Python + frontend project for scraping and displaying job data.
   - This means jobs are not just read from one API at runtime; there is an ingestion layer that normalizes external listings into a platform-owned job dataset.

12. **Job matching and skill normalization**
   - The backend job recommendation layer uses `backend/services/jobRecommendationService.js` and `backend/lib/skillNormalizer.js`.
   - Architecturally, this is the bridge between the platform’s internal skill model and inconsistent external job postings.
   - The presence of skill normalization suggests job matching depends on canonical skill tags, not raw title/keyword matching only.

13. **Resume pipeline**
   - Resume handling is one of the more complex subsystems.
   - The frontend lets users upload/build resumes; `src/services/resumeParser/` extracts structured sections from PDF text.
   - The backend then supports resume persistence, PDF generation, certificate generation, and probably AI enhancement.
   - The architecture here is: upload/read PDF in the browser, extract structured data client-side, persist and enrich through backend services.

14. **Deployment and environment boundaries**
   - Configuration is split by runtime: frontend env variables use `VITE_` prefixes, while the backend has its own `.env`.
   - Deployment files like `render.yaml` and `vercel.json` indicate the app is intended for cloud deployment with separate frontend/backend concerns.
   - The repo also contains operational docs for authentication, roadmap flows, migration, and deployment, which suggests the architecture has evolved through multiple feature phases and service integrations.

15. **What an architecture diagram should show**
   - At minimum, draw these nodes and flows:
     - **Browser SPA** → Supabase auth/database + backend API
     - **Browser SPA** → web workers for code execution
     - **Backend API** → Postgres/Supabase, OpenRouter, email service, PDF generation, job APIs
     - **Job ingestion/scraper subsystem** → job data store used by the main app
     - **Static content/data layer** inside the frontend for roadmaps, quizzes, and career catalogs
   - The key boundary is that the frontend owns presentation and much of the content model, while the backend owns secrets, integrations, and server-side business logic.

Main entry points: [`backend/services`](https://github.com/vickykumarofficial/arcade-learn/tree/main/backend/services) (Backend services), [`src/pages`](https://github.com/vickykumarofficial/arcade-learn/tree/main/src/pages) (Pages), [`src/services`](https://github.com/vickykumarofficial/arcade-learn/tree/main/src/services) (Client services), [`backend/server.js`](https://github.com/vickykumarofficial/arcade-learn/blob/main/backend/server.js) (API entrypoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_src_main(("App bootstrap<br/>SPA entry<br/>[main.tsx]"))
  node_src_pages["Pages<br/>route views"]
  node_src_components["UI components<br/>shared UI"]
  node_src_contexts["App state<br/>react context"]
  node_src_hooks_lib["Client logic<br/>hooks and libs"]
  node_src_services["Client services<br/>service layer"]
  node_src_workers["Code workers<br/>web workers"]
end

subgraph group_backend["Backend API"]
  node_backend_server(("API entrypoint<br/>node server<br/>[server.js]"))
  node_backend_services["Backend services<br/>integration services"]
  node_backend_lib["Backend libs<br/>db and utils"]
  node_backend_jobs["Job fetchers<br/>job ingestion"]
end

subgraph group_jobs["Jobs Pipeline"]
  node_job_scraper["Scraper app<br/>python+ui"]
  node_job_scraper_backend["Scraper backend<br/>python scraper<br/>[scraper.py]"]
  node_job_scraper_frontend["Jobs UI<br/>react frontend"]
end

subgraph group_shared["Shared Data"]
  node_src_data[("Content data<br/>static datasets")]
  node_db_schema["Schemas<br/>sql migrations"]
  node_resume_store[("Resume files<br/>file storage")]
  node_deploy_config["Deploy config<br/>platform config<br/>[render.yaml]"]
end

node_src_main -->|"routes"| node_src_pages
node_src_pages -->|"renders"| node_src_components
node_src_pages -->|"state"| node_src_contexts
node_src_pages -->|"reads"| node_src_data
node_src_components -->|"content"| node_src_data
node_src_components -->|"actions"| node_src_services
node_src_contexts -->|"uses"| node_src_hooks_lib
node_src_services -->|"api calls"| node_backend_server
node_src_services -->|"executes"| node_src_workers
node_src_services -->|"reads/writes"| node_resume_store
node_backend_server -->|"orchestrates"| node_backend_services
node_backend_server -->|"uses"| node_backend_lib
node_backend_services -->|"persists"| node_db_schema
node_backend_services -->|"manages"| node_resume_store
node_backend_services -.->|"content-aware"| node_src_data
node_backend_services -->|"enriches"| node_job_scraper_backend
node_backend_jobs -->|"loads jobs"| node_db_schema
node_job_scraper -->|"contains"| node_job_scraper_backend
node_job_scraper -->|"contains"| node_job_scraper_frontend
node_job_scraper_frontend -.->|"queries"| node_db_schema
node_backend_lib -->|"schema-aware"| node_db_schema
node_backend_lib -.->|"normalizes"| node_src_data
node_deploy_config -.->|"hosts"| node_src_main
node_deploy_config -.->|"deploys"| node_backend_server

click node_src_main "https://github.com/vickykumarofficial/arcade-learn/blob/main/src/main.tsx"
click node_src_pages "https://github.com/vickykumarofficial/arcade-learn/tree/main/src/pages"
click node_src_components "https://github.com/vickykumarofficial/arcade-learn/tree/main/src/components"
click node_src_contexts "https://github.com/vickykumarofficial/arcade-learn/tree/main/src/contexts"
click node_src_hooks_lib "https://github.com/vickykumarofficial/arcade-learn/tree/main/src/hooks"
click node_src_data "https://github.com/vickykumarofficial/arcade-learn/tree/main/src/data"
click node_src_services "https://github.com/vickykumarofficial/arcade-learn/tree/main/src/services"
click node_src_workers "https://github.com/vickykumarofficial/arcade-learn/tree/main/src/workers"
click node_backend_server "https://github.com/vickykumarofficial/arcade-learn/blob/main/backend/server.js"
click node_backend_services "https://github.com/vickykumarofficial/arcade-learn/tree/main/backend/services"
click node_backend_lib "https://github.com/vickykumarofficial/arcade-learn/tree/main/backend/lib"
click node_backend_jobs "https://github.com/vickykumarofficial/arcade-learn/blob/main/backend/fetch-adzuna-jobs.js"
click node_job_scraper "https://github.com/vickykumarofficial/arcade-learn/tree/main/job-scraper"
click node_job_scraper_backend "https://github.com/vickykumarofficial/arcade-learn/blob/main/job-scraper/backend/scraper/scraper.py"
click node_job_scraper_frontend "https://github.com/vickykumarofficial/arcade-learn/tree/main/job-scraper/frontend/src"
click node_db_schema "https://github.com/vickykumarofficial/arcade-learn/tree/main/database"
click node_resume_store "https://github.com/vickykumarofficial/arcade-learn/tree/main/data/resumes"
click node_deploy_config "https://github.com/vickykumarofficial/arcade-learn/blob/main/render.yaml"

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_src_main,node_src_pages,node_src_components,node_src_contexts,node_src_hooks_lib,node_src_services,node_src_workers toneBlue
class node_backend_server,node_backend_services,node_backend_lib,node_backend_jobs toneAmber
class node_job_scraper,node_job_scraper_backend,node_job_scraper_frontend toneMint
class node_src_data,node_db_schema,node_resume_store,node_deploy_config toneRose
```

## Components

### Frontend SPA

React/TypeScript browser app with content-driven learning features.

- [App bootstrap](https://github.com/vickykumarofficial/arcade-learn/blob/main/src/main.tsx): SPA entry · Vite/React entrypoint and top-level app shell. · `src/main.tsx`
- [Pages](https://github.com/vickykumarofficial/arcade-learn/tree/main/src/pages): route views · Primary feature pages for roadmap, careers, AI, resume, and practice flows. · `src/pages`
- [UI components](https://github.com/vickykumarofficial/arcade-learn/tree/main/src/components): shared UI · Reusable presentation layer including product sections and shadcn-style primitives. · `src/components`
- [App state](https://github.com/vickykumarofficial/arcade-learn/tree/main/src/contexts): react context · Shared client state for auth, survey, resume builder, and game test flows. · `src/contexts`
- [Client logic](https://github.com/vickykumarofficial/arcade-learn/tree/main/src/hooks): hooks and libs · Reusable client-side behavior for recommendations, gamification, auth, and roadmap progress. · `src/hooks`
- [Client services](https://github.com/vickykumarofficial/arcade-learn/tree/main/src/services): service layer · Browser boundary for AI, quiz, resume, progress, activity, and email workflows. · `src/services`
- [Code workers](https://github.com/vickykumarofficial/arcade-learn/tree/main/src/workers): web workers · Isolated execution workers for JavaScript/TypeScript and Python code. · `src/workers`

### Backend API

Node.js orchestration layer for integrations, persistence, and server-side features.

- [API entrypoint](https://github.com/vickykumarofficial/arcade-learn/blob/main/backend/server.js): node server · Central backend router and server-side orchestration entrypoint. · `backend/server.js`
- [Backend services](https://github.com/vickykumarofficial/arcade-learn/tree/main/backend/services): integration services · Server-side capabilities for AI, resume, email, PDF, scoring, subscriptions, and tracking. · `backend/services`
- [Backend libs](https://github.com/vickykumarofficial/arcade-learn/tree/main/backend/lib): db and utils · Database access, Supabase admin client, and skill normalization utilities. · `backend/lib`
- [Job fetchers](https://github.com/vickykumarofficial/arcade-learn/blob/main/backend/fetch-adzuna-jobs.js): job ingestion · Node scripts that fetch external job data into the platform pipeline. · `backend/fetch-adzuna-jobs.js`

### Jobs Pipeline

Separate job ingestion and browsing subsystem.

- [Scraper app](https://github.com/vickykumarofficial/arcade-learn/tree/main/job-scraper): python+ui · Separate Python scraping backend plus a small frontend for job browsing. · `job-scraper`
- [Scraper backend](https://github.com/vickykumarofficial/arcade-learn/blob/main/job-scraper/backend/scraper/scraper.py): python scraper · Selectors and Python scraper logic for collecting job listings. · `job-scraper/backend/scraper/scraper.py`
- [Jobs UI](https://github.com/vickykumarofficial/arcade-learn/tree/main/job-scraper/frontend/src): react frontend · Standalone job browsing frontend for the scraper subsystem. · `job-scraper/frontend/src`

### Shared Data

Repository-level data and schema assets used across runtimes.

- [Content data](https://github.com/vickykumarofficial/arcade-learn/tree/main/src/data): static datasets · Compiled learning content, roadmaps, problems, FAQs, testimonials, and career metadata. · `src/data`
- [Schemas](https://github.com/vickykumarofficial/arcade-learn/tree/main/database): sql migrations · Repository SQL for resumes, surveys, jobs, activity tracking, scores, and AI feedback. · `database`
- [Resume files](https://github.com/vickykumarofficial/arcade-learn/tree/main/data/resumes): file storage · Local resume artifact snapshots and parsed resume JSON. · `data/resumes`
- [Deploy config](https://github.com/vickykumarofficial/arcade-learn/blob/main/render.yaml): platform config · Render and Vercel deployment configuration and environment boundaries. · `render.yaml`

## Connections

- App bootstrap → Pages: routes · Bootstraps the routed application shell.
- Pages → UI components: renders · Pages compose shared product and UI components.
- Pages → App state: state · Pages consume shared client contexts for auth and flows.
- Pages → Content data: reads · Feature pages render from bundled roadmap, career, and practice datasets.
- UI components → Content data: content · Components use structured learning content and metadata.
- UI components → Client services: actions · Interactive UI delegates side effects through service modules.
- App state → Client logic: uses · Contexts rely on shared hooks and client business logic.
- Client services → API entrypoint: api calls · Client services talk to the backend for protected and server-side operations.
- Client services → Code workers: executes · Code execution services delegate untrusted code to web workers.
- Client services → Resume files: reads/writes · Resume flows persist parsed and generated artifacts.
- API entrypoint → Backend services: orchestrates · Server routes fan out into focused backend services.
- API entrypoint → Backend libs: uses · Request handling depends on database and utility libraries.
- Backend services → Schemas: persists · Backend services store and query platform data through schema-backed tables.
- Backend services → Resume files: manages · Resume service flows also use local resume artifact storage.
- Backend services → Content data: content-aware · Some server flows align with frontend-owned roadmap and skill models.
- Backend services → Scraper backend: enriches · Job recommendation and matching can consume scraped listings.
- Job fetchers → Schemas: loads jobs · External job ingestion feeds the platform's jobs storage.
- Scraper app → Scraper backend: contains · The scraper subsystem includes the Python ingestion backend.
- Scraper app → Jobs UI: contains · The scraper subsystem also ships its own browsing UI.
- Jobs UI → Schemas: queries · Standalone jobs UI reads from the shared job data backend.
- Backend libs → Schemas: schema-aware · Database helpers connect to the repository's Postgres schema.
- Backend libs → Content data: normalizes · Shared skill and matching logic aligns with the app's content model.
- Deploy config → App bootstrap: hosts · Frontend build and hosting configuration target the browser app.
- Deploy config → API entrypoint: deploys · Deployment config also covers backend runtime placement.
