Current production architecture

GradStudio platform map

A current view of the GradStudio learning platform after the latest homepage, carousel, account, pins, admin, and cleanup changes.

View diagram Latest changes

Overview

What runs the product

The app is split into a static learner experience, a browser admin editor, and a Cloudflare Worker backend that owns routing, auth, data, and object storage.

Learner frontend

Homepage, course catalog, player, About page, account menu, pinned courses/modules, and responsive carousel UI.

static/index.html gradstudio-learn-demo.js gradstudio-learn-demo.css

Admin editor

Course/folder editing, simulation upload, carousel layout editing, card sizing, frame style, course-list selection, and search.

gradstudio-learn-admin.html gradstudio-learn-admin.js

Cloudflare backend

A single Worker dispatches public APIs, admin APIs, auth, R2 file serving, D1 queries, KV config, and cache headers.

worker/src/index.js worker/wrangler.toml

Interactive diagram

Request path

Click any node to see what it does and where it lives in the codebase.

Browser

Cloudflare edge

Worker router

Data and storage

Operations

Learner app

The main GradStudio experience served to learners.

Responsibilities

Updated node map

Current GradStudio graph

This is the same request path shown as a connected node graph, updated for the latest hero, carousel, account pins, admin editor, Worker, D1, R2, and KV changes.

HTML shell

The browser starts with the static GradStudio shell.

Current responsibilities

Runtime flows

How features move through the stack

The current app uses the same Worker for page serving and API calls, with D1/KV/R2 selected by the request type.

Homepage and carousel rendering

Browser loads static shell`index.html` loads `gradstudio-learn-demo.css` and `gradstudio-learn-demo.js` with the current cache key.

Frontend requests carousel config`/api/learn-carousels` returns normalized hero, big carousel, bottom carousel, text blocks, and extra carousel layers.

Worker reads KV config`gradstudio-learn-carousels:{environment}` stores the modern layout config; legacy carousel rows remain supported.

Frontend sizes cardsThe first active card height controls carousel card height. Width remains per-card. Arrows show when a carousel has more than one visible/scrollable card.

Images and HTML assets resolveR2 serves hero images, carousel images, static HTML lessons, and admin uploaded assets.

Course catalog, detail, and player

Catalog loads courses`/api/courses` returns folders, courses, thumbnails, section counts, and searchable metadata.

Course opens`/api/courses/:courseId` hydrates sections and simulations for the detail page or player route.

Lesson content loads`/simulations/...` or `/api/simulations/:slug` pulls lesson HTML from R2 and applies safe serving headers.

Engagement savesViews, likes, dislikes, comments, reports, bookmarks, and analytics are written to D1.

Account, Google sign-in, and pinned learning

Account actions start in the browserSignup/signin forms or Google token client call Worker auth endpoints.

Worker creates auth stateD1 stores users/sessions. KV namespaces store refresh tokens and rate limits.

Account menu renders user contextThe user chip dropdown shows the logged-in name/email, pinned access, and logout actions.

Pins sync to the account`GET /api/user-pins` and `PUT /api/user-pins` keep pinned courses/modules tied to the authenticated user.

Admin editing and publishing

Admin loads current data`gradstudio-learn-admin.js` pulls courses, categories, and carousel layout through authenticated admin routes.

Editor changes contentAdmins update folders, course data, sections, simulations, carousel layout blocks, and card settings.

Uploads go to R2Simulation files and carousel media are stored as R2 objects with generated object paths.

Data saves to D1/KVCourse rows and old carousel cards use D1; modern learn carousel layout uses KV through `/api/admin/learn-carousels`.

Deployment and cache behavior

Static files are uploaded to R2Production uses the `static/` prefix. Dev uses the `dev-static/` prefix.

Worker deploy controls routes`wrangler.toml` maps production domains and API custom domain to `worker/src/index.js`.

Cache keys bust frontend assetsHTML references CSS/JS with a version query string, currently `20260429-architecture-search-v49`.

Local junk stays local`USELESS/` contains previews/backups/profiles and is ignored by Git.

API surface

Current route groups

The Worker file is the main route dispatcher. These are the important public, account, and admin route groups it exposes.

Public learning

GET/api/courses

GET/api/courses/:courseId

GET/api/categories

GET/api/learn-carousels

GET/api/search?q=...

GET/api/recent

Auth and account

POST/api/auth/register

POST/api/auth/login

POST/api/auth/google/token

GET/api/auth/me

POST/api/auth/refresh

GET/api/user-pins

PUT/api/user-pins

Engagement

POST/api/views/:simId

POST/api/likes/:simId

POST/api/dislikes/:simId

GET/api/comments/:simId

POST/api/comments/:simId

POST/api/reports/:simId

POST/api/bookmarks/:simId

Admin content

POST/api/admin/courses

PUT/api/admin/courses

DEL/api/admin/courses/:id

POST/api/admin/categories

POST/api/admin/sections

POST/api/admin/simulations

POST/api/admin/upload-simulation

Admin carousel

GET/api/admin/learn-carousels

PUT/api/admin/learn-carousels

GET/api/admin/carousels

POST/api/admin/carousels

POST/api/admin/carousel

PUT/api/admin/carousel

POST/api/admin/carousel/upload

Admin operations

POST/api/admin/sync-content

POST/api/admin/bulk-upload

GET/api/admin/users

POST/api/admin/users/:id/role

POST/api/admin/metrics/unlock-account

Data model

Persistent storage

D1 owns relational content and user data. KV owns high-speed config/tokens/rate limits. R2 owns static files, simulations, and uploaded media.

Storage	Key tables or keys	Purpose	Recent relevance
D1	`categories`, `courses`, `sections`, `simulations`	Course catalog hierarchy, modules, lessons, thumbnails, and searchable metadata.	Admin search/select now depends on clean folder/course metadata.
D1	`carousels`, `carousel_cards`	Legacy and compatibility storage for carousel rows and card media metadata.	Still supported while new learn carousel config is stored through KV.
D1	`users`, `sessions`, `user_pins`	Account identity, session history, and account-backed pinned courses/modules.	`2026-04-28-add-user-pins.sql` adds the pins table and index.
D1	`comments`, `likes`, `bookmarks`, `reports`, analytics tables	Learner engagement, feedback, safety reports, and usage metrics.	Player and course pages can write engagement without changing static files.
KV	`gradstudio-learn-carousels:{env}`, refresh tokens, rate limits	Fast config reads, auth refresh state, and request throttling.	Modern homepage layout blocks and card sizing are saved here.
R2	`static/`, `dev-static/`, `carousel/images/`, simulations	HTML/CSS/JS assets, generated images, lesson files, uploaded carousel media.	Hero image and production frontend assets are served from R2.

Source map

Files that matter now

These are the current files to inspect before making future architecture or product changes.

static/index.htmlMain production shell: top nav, hero, catalog, player mount points, auth/info page mount points, footer, CSS/JS cache keys.

static/gradstudio-learn-demo.htmlStandalone copy of the learner app shell for the GradStudio Learn demo path.

static/gradstudio-learn-demo.cssCurrent responsive design, hero sizing, carousel cropping fixes, account menu, pins UI, About page, player density, and mobile rules.

static/gradstudio-learn-demo.jsMain learner app logic: routing, catalog render, carousel render, account menu, Google sign-in, pinned items, course detail, player, About/contact/legal pages.

static/hero-gradstudio-20260429-152846.pngCurrent hero image asset referenced by the homepage and carousel card config.

static/gradstudio-learn-admin.htmlAdmin editor shell for course, folder, simulation, and carousel management.

static/gradstudio-learn-admin.jsAdmin logic for course/folder editing, carousel layout blocks, card editor, height rule, frame style, course selector, and search.

worker/src/index.jsMain Cloudflare Worker entry and route dispatcher for public, auth, user, admin, R2, D1, and KV behavior.

worker/wrangler.tomlProduction/dev routes, D1 binding, R2 bucket binding, KV namespaces, static/admin prefixes, environment variables.

worker/schema.sqlBaseline schema for courses, simulations, users, comments, bookmarks, analytics, and carousel tables.

worker/migrations/2026-04-28-add-user-pins.sqlLatest user pins persistence migration.

.gitignoreIgnores `USELESS/`, local browser profiles, logs, temp files, archives, dependencies, and local environment files.

Latest changes reflected

What changed recently

This page reflects the latest production work that changed the platform behavior and folder structure.

Homepage and visual polish

Hero image changed to `hero-gradstudio-20260429-152846.png`.
Hero visual uses a stable image/card layout instead of browser-zoom-dependent cropping.
About page rewritten with first-person Sabareesh wording and a natural image frame.
Current frontend cache key is `20260429-architecture-search-v49`.

Carousel behavior

Carousel arrows show when there is more than one scrollable card.
Right-edge clipping was addressed with viewport-constrained block width and scroll padding.
The first active card height now sets every card height in that carousel. Width remains per-card.
Card frame style can be framed or flush for borderless page-color designs.

Admin editor

Course display picker was rebuilt around Folder/Courses selection and direct search.
Admin carousel card editor supports course-list cards, search/select, dimensions, colors, text positioning, and frame style.
Modern homepage layout blocks are saved through `/api/admin/learn-carousels`.

Account and cleanup

Account chip opens a real account menu with name/email, My pinned, and logout.
Pinned courses/modules sync to D1 per logged-in account.
Local bloat was moved to `USELESS/`; it is ignored by Git and not needed for the app to run.
GitHub cleanup removed old previews/backups/prototypes from tracked project files.

Operational note: deleting `USELESS/` will not break production or the local app. It only removes local backups, previews, old downloaded codebase copies, browser profiles, and scratch files that were moved out of the active source tree.