# coding-club-iitg/coursehub architecture

> Architecture diagram of the GitHub repository coding-club-iitg/coursehub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coding-club-iitg/coursehub
- Repository: https://github.com/coding-club-iitg/coursehub

## Overview

1. This is a monorepo with three main runtime surfaces: `client` for the public user-facing app, `admin` for internal administration, and `server` for the backend API. A small `utils/make-courses` Go utility and several server scripts support data generation and maintenance.

2. The public `client` is a React + Vite single-page app. Its screens are organized by user journey: landing/search, browse file tree, dashboard, contributions, profile, share, and error states. It uses its own router guard, reusable UI components, and a Redux-style state layer (`actions`, `reducers`) for file browser, URLs, and user state.

3. The `admin` app is a separate React + Vite SPA for operational staff. Its main pages cover login, branch representatives, courses, students, and course-linking. It also has a private-route wrapper, indicating authenticated-only access and a distinct admin auth flow.

4. The backend is a modular Node/Express-style API under `server/modules`. Each domain has the same boundary pattern: route file, controller, and usually a model/service layer. Core domains include auth, admin, user, course, folder, file, year, contribution, search, student, BR, event, and OneDrive integration.

5. Authentication and authorization are enforced on the server with dedicated middleware: `isAuthenticated`, `isAdmin`, and `isBR`. There are separate auth flows for normal users and admins, plus an OTP/auth-admin subsystem, which suggests role-based access rather than a single flat login model.

6. The application’s primary data model is academic content organized by year, course, folder, and file. The client browse/dashboard/profile screens consume these APIs to render course catalogs, file trees, favorites, exam cards, and contribution records. The server’s `search`, `course`, `folder`, `file`, and `year` modules form the backbone of that content graph.

7. Contributions are a first-class workflow. The public app has contribution screens and per-item contribution cards, while the server has a dedicated contribution module. This implies user-submitted content enters a moderation/approval path rather than being directly published.

8. External storage and file delivery are important boundaries. The server includes an `onedrive` module, OneDrive configuration, and a device-code token file, so academic files are at least partially sourced from or synchronized with OneDrive. There is also an `imagekit` service and an email service, suggesting media handling and notification workflows.

9. Course metadata is generated and maintained through offline tooling. The repo includes `server/modules/course/create_courses.py`, `course/list.json`, server scripts for seeding, migration, and cleanup, and a separate Go utility that reads an Excel file to generate course data. That means course catalog data is partly curated outside the live API and then imported.

10. Caching and lookup behavior are explicit architecture concerns in the public client. There are utility modules for frontend cache, course cache, folder search, formatting, and course-link logic docs. These reduce repeated API calls and help keep browse/search interactions responsive.

11. Build and deployment are split by surface. Both frontends have their own Vite configs and env examples, while the server has its own package, static assets, and deployment script. The apps are therefore independently buildable, but they share a common backend API contract.

12. For an architecture diagram, the main boundaries are: public client ↔ API server, admin client ↔ API server, and API server ↔ database/storage/external services. Inside the server, the key internal flow is route → controller → model/service → persistence or external integration.

Main entry points: [`client/src/App.jsx`](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/App.jsx) (Client UI), [`server/index.js`](https://github.com/coding-club-iitg/coursehub/blob/dev/server/index.js) (Server API), [`admin/src/App.jsx`](https://github.com/coding-club-iitg/coursehub/blob/dev/admin/src/App.jsx) (Admin UI), [`server/modules/course/course.routes.js`](https://github.com/coding-club-iitg/coursehub/blob/dev/server/modules/course/course.routes.js) (Domain modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client app"]
  node_client_app["Client UI<br/>React SPA<br/>[App.jsx]"]
  node_client_router["Private route<br/>route guard<br/>[PrivateRoutes.jsx]"]
  node_client_state["State layer<br/>Redux-like state<br/>[index.js]"]
  node_client_browser["Browse flow<br/>screen subsystem<br/>[index.jsx]"]
  node_client_landing["Landing search<br/>screen subsystem<br/>[index.jsx]"]
  node_client_dashboard["Dashboard<br/>screen subsystem<br/>[index.jsx]"]
  node_client_contrib["Contributions<br/>screen subsystem<br/>[index.jsx]"]
  node_client_profile["Profile<br/>screen subsystem<br/>[index.jsx]"]
  node_client_share["Share<br/>screen subsystem<br/>[index.jsx]"]
  node_client_utils["Client utils<br/>helpers/cache<br/>[frontendCache.js]"]
end

subgraph group_admin["Admin app"]
  node_admin_app["Admin UI<br/>React SPA<br/>[App.jsx]"]
  node_admin_router["Private route<br/>route guard<br/>[PrivateRoutes.jsx]"]
  node_admin_auth["Admin login<br/>auth flow<br/>[Login.jsx]"]
  node_admin_ops["Ops pages<br/>screen subsystem<br/>[Courses.jsx]"]
end

subgraph group_server["API server"]
  node_server_api["Server API<br/>Express API<br/>[index.js]"]
  node_server_auth["Auth & roles<br/>security middleware<br/>[isAuthenticated.js]"]
  node_server_domains["Domain modules<br/>module suite<br/>[course.routes.js]"]
  node_server_content["Content graph<br/>content domains<br/>[year.routes.js]"]
  node_server_integrations["Integrations<br/>external services<br/>[onedrive.routes.js]"]
  node_server_ops["Maintenance scripts<br/>ops scripts<br/>[seed_app.js]"]
end

subgraph group_tooling["Offline tooling"]
  node_tool_go["Go generator<br/>Excel import tool<br/>[main.go]"]
end

node_client_app -->|"protect routes"| node_client_router
node_client_app -->|"manage state"| node_client_state
node_client_app -->|"browse"| node_client_browser
node_client_app -->|"search"| node_client_landing
node_client_app -->|"dashboard"| node_client_dashboard
node_client_app -->|"contribute"| node_client_contrib
node_client_app -->|"profile"| node_client_profile
node_client_app -->|"share"| node_client_share
node_client_app -->|"cache/format"| node_client_utils
node_admin_app -->|"restrict access"| node_admin_router
node_admin_app -->|"sign in"| node_admin_auth
node_admin_app -->|"manage ops"| node_admin_ops
node_client_app -.->|"API calls"| node_server_api
node_admin_app -.->|"API calls"| node_server_api
node_server_api -->|"enforce roles"| node_server_auth
node_server_api -->|"mount modules"| node_server_domains
node_server_domains -->|"content APIs"| node_server_content
node_server_domains -->|"external sync"| node_server_integrations
node_server_api -.->|"maintenance"| node_server_ops
node_server_domains -->|"auth endpoints"| node_server_auth
node_server_ops -.->|"generate courses"| node_tool_go

click node_client_app "https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/App.jsx"
click node_client_router "https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/router_utils/PrivateRoutes.jsx"
click node_client_state "https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/reducers/index.js"
click node_client_browser "https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/browse/index.jsx"
click node_client_landing "https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/landing/index.jsx"
click node_client_dashboard "https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/dashboard/index.jsx"
click node_client_contrib "https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/contributions/index.jsx"
click node_client_profile "https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/profile.js/index.jsx"
click node_client_share "https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/share/index.jsx"
click node_client_utils "https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/utils/frontendCache.js"
click node_admin_app "https://github.com/coding-club-iitg/coursehub/blob/dev/admin/src/App.jsx"
click node_admin_router "https://github.com/coding-club-iitg/coursehub/blob/dev/admin/src/router_utils/PrivateRoutes.jsx"
click node_admin_auth "https://github.com/coding-club-iitg/coursehub/blob/dev/admin/src/pages/Login.jsx"
click node_admin_ops "https://github.com/coding-club-iitg/coursehub/blob/dev/admin/src/pages/Courses.jsx"
click node_server_api "https://github.com/coding-club-iitg/coursehub/blob/dev/server/index.js"
click node_server_auth "https://github.com/coding-club-iitg/coursehub/blob/dev/server/middleware/isAuthenticated.js"
click node_server_domains "https://github.com/coding-club-iitg/coursehub/blob/dev/server/modules/course/course.routes.js"
click node_server_content "https://github.com/coding-club-iitg/coursehub/blob/dev/server/modules/year/year.routes.js"
click node_server_integrations "https://github.com/coding-club-iitg/coursehub/blob/dev/server/modules/onedrive/onedrive.routes.js"
click node_server_ops "https://github.com/coding-club-iitg/coursehub/blob/dev/server/scripts/seed_app.js"
click node_tool_go "https://github.com/coding-club-iitg/coursehub/blob/dev/utils/make-courses/cmd/app/main.go"

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_client_app,node_client_router,node_client_state,node_client_browser,node_client_landing,node_client_dashboard,node_client_contrib,node_client_profile,node_client_share,node_client_utils toneBlue
class node_admin_app,node_admin_router,node_admin_auth,node_admin_ops toneAmber
class node_server_api,node_server_auth,node_server_domains,node_server_content,node_server_integrations,node_server_ops toneMint
class node_tool_go toneRose
```

## Components

### Client app

Public React + Vite SPA for learners and contributors.

- [Client UI](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/App.jsx): React SPA · Public user-facing application with browse, dashboard, profile, share, and contribution flows. · `client/src/App.jsx`
- [Private route](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/router_utils/PrivateRoutes.jsx): route guard · Client-side access control wrapper for protected screens. · `client/src/router_utils/PrivateRoutes.jsx`
- [State layer](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/reducers/index.js): Redux-like state · Actions and reducers for file browser, URLs, and user state. · `client/src/reducers/index.js`
- [Browse flow](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/browse/index.jsx): screen subsystem · File tree browsing, folder/file display, year and folder actions. · `client/src/screens/browse/index.jsx`
- [Landing search](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/landing/index.jsx): screen subsystem · Entry screen and search modal for finding courses and content. · `client/src/screens/landing/index.jsx`
- [Dashboard](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/dashboard/index.jsx): screen subsystem · Course cards, favourites, exams, and contribution banner for signed-in users. · `client/src/screens/dashboard/index.jsx`
- [Contributions](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/contributions/index.jsx): screen subsystem · Public contribution views and per-item contribution cards. · `client/src/screens/contributions/index.jsx`
- [Profile](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/profile.js/index.jsx): screen subsystem · User profile and contribution history views. · `client/src/screens/profile.js/index.jsx`
- [Share](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/screens/share/index.jsx): screen subsystem · Sharing surface for course/content links. · `client/src/screens/share/index.jsx`
- [Client utils](https://github.com/coding-club-iitg/coursehub/blob/dev/client/src/utils/frontendCache.js): helpers/cache · Formatting, search, and caching helpers that reduce repeated API work. · `client/src/utils/frontendCache.js`

### Admin app

Private React + Vite SPA for operational staff.

- [Admin UI](https://github.com/coding-club-iitg/coursehub/blob/dev/admin/src/App.jsx): React SPA · Internal administration application for staff workflows. · `admin/src/App.jsx`
- [Private route](https://github.com/coding-club-iitg/coursehub/blob/dev/admin/src/router_utils/PrivateRoutes.jsx): route guard · Admin-only access wrapper and authenticated navigation. · `admin/src/router_utils/PrivateRoutes.jsx`
- [Admin login](https://github.com/coding-club-iitg/coursehub/blob/dev/admin/src/pages/Login.jsx): auth flow · Admin authentication screens and API wiring. · `admin/src/pages/Login.jsx`
- [Ops pages](https://github.com/coding-club-iitg/coursehub/blob/dev/admin/src/pages/Courses.jsx): screen subsystem · Branch representatives, courses, students, and course-linking administration. · `admin/src/pages/Courses.jsx`

### API server

Node/Express backend, domain modules, integrations, and scripts.

- [Server API](https://github.com/coding-club-iitg/coursehub/blob/dev/server/index.js): Express API · Main backend entrypoint wiring middleware, modules, and static assets. · `server/index.js`
- [Auth & roles](https://github.com/coding-club-iitg/coursehub/blob/dev/server/middleware/isAuthenticated.js): security middleware · Authentication and role checks for users, admins, and BRs. · `server/middleware/isAuthenticated.js`
- [Domain modules](https://github.com/coding-club-iitg/coursehub/blob/dev/server/modules/course/course.routes.js): module suite · Route-controller-model boundaries for auth, admin, user, course, folder, file, year, contribution, search, student, BR, and event. · `server/modules/course/course.routes.js`
- [Content graph](https://github.com/coding-club-iitg/coursehub/blob/dev/server/modules/year/year.routes.js): content domains · Academic hierarchy and discovery backbone across year, course, folder, file, and search. · `server/modules/year/year.routes.js`
- [Integrations](https://github.com/coding-club-iitg/coursehub/blob/dev/server/modules/onedrive/onedrive.routes.js): external services · OneDrive, email, image processing, and upload boundaries. · `server/modules/onedrive/onedrive.routes.js`
- [Maintenance scripts](https://github.com/coding-club-iitg/coursehub/blob/dev/server/scripts/seed_app.js): ops scripts · Seeding, migration, cleanup, and import scripts for the live dataset. · `server/scripts/seed_app.js`

### Offline tooling

Data-generation utilities and import helpers.

- [Go generator](https://github.com/coding-club-iitg/coursehub/blob/dev/utils/make-courses/cmd/app/main.go): Excel import tool · Standalone utility that generates course data from spreadsheet input. · `utils/make-courses/cmd/app/main.go`

## Connections

- Client UI → Private route: protect routes · Wrap protected screens with client-side access control.
- Client UI → State layer: manage state · Coordinate browse, URL, and user state through actions and reducers.
- Client UI → Browse flow: browse · Navigate the file tree and content hierarchy.
- Client UI → Landing search: search · Start course discovery from the landing page.
- Client UI → Dashboard: dashboard · Render user dashboard summaries and cards.
- Client UI → Contributions: contribute · Open contribution workflows and records.
- Client UI → Profile: profile · Show user profile and contribution history.
- Client UI → Share: share · Present sharing flows and link surfaces.
- Client UI → Client utils: cache/format · Use caching and formatting helpers to keep interactions responsive.
- Admin UI → Private route: restrict access · Gate internal pages behind authenticated-only routing.
- Admin UI → Admin login: sign in · Use the separate admin authentication flow.
- Admin UI → Ops pages: manage ops · Handle staff workflows for BRs, courses, students, and linking.
- Client UI → Server API: API calls · Public SPA consumes backend endpoints.
- Admin UI → Server API: API calls · Admin SPA consumes backend endpoints.
- Server API → Auth & roles: enforce roles · Apply authentication and role middleware to protected routes.
- Server API → Domain modules: mount modules · Expose domain-specific routers under the main API.
- Domain modules → Content graph: content APIs · Course, year, folder, file, and search form the core content graph.
- Domain modules → Integrations: external sync · Integrate with OneDrive, email, imagekit, and upload services.
- Server API → Maintenance scripts: maintenance · Run seeding, migration, cleanup, and import scripts alongside the API.
- Domain modules → Auth & roles: auth endpoints · Separate user, admin, and OTP/auth-admin flows from content APIs.
- Maintenance scripts → Go generator: generate courses · Offline tooling feeds curated course data into the server dataset.
