How vickykumarofficial/arcade-learn works
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 Backend services · pages Pages · src/services Client services · server.js API entrypoint
Components 18
Frontend SPA
React/TypeScript browser app with content-driven learning features.
- App bootstrap · Vite/React entrypoint and top-level app shell.
src/main.tsx - Pages · Primary feature pages for roadmap, careers, AI, resume, and practice flows.
src/pages - UI components · Reusable presentation layer including product sections and shadcn-style primitives.
src/components - App state · Shared client state for auth, survey, resume builder, and game test flows.
src/contexts - Client logic · Reusable client-side behavior for recommendations, gamification, auth, and roadmap progress.
src/hooks - Client services · Browser boundary for AI, quiz, resume, progress, activity, and email workflows.
src/services - Code 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 · Central backend router and server-side orchestration entrypoint.
backend/server.js - Backend services · Server-side capabilities for AI, resume, email, PDF, scoring, subscriptions, and tracking.
backend/services - Backend libs · Database access, Supabase admin client, and skill normalization utilities.
backend/lib - Job fetchers · 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 · Separate Python scraping backend plus a small frontend for job browsing.
job-scraper - Scraper backend · Selectors and Python scraper logic for collecting job listings.
job-scraper/backend/scraper/scraper.py - Jobs UI · 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 · Compiled learning content, roadmaps, problems, FAQs, testimonials, and career metadata.
src/data - Schemas · Repository SQL for resumes, surveys, jobs, activity tracking, scores, and AI feedback.
database - Resume files · Local resume artifact snapshots and parsed resume JSON.
data/resumes - Deploy config · Render and Vercel deployment configuration and environment boundaries.
render.yaml
Connections 24
- 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.