# mark20042/gradsync architecture

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

- Interactive diagram: https://gitdiagram.com/mark20042/gradsync
- Repository: https://github.com/mark20042/gradsync

## Overview

1. **Overall shape**
   - GradSync is a two-tier monorepo: a **React/Vite client** in `client/` and a **TypeScript/Express API** in `new-sirbir/`.
   - The frontend handles all user-facing workflows; the backend owns authentication, business rules, persistence, AI orchestration, and integrations.

2. **Client-side presentation layer**
   - The client is organized by **user role and workflow**, not by technical layer.
   - Major UI areas are `LandingPage`, `Auth`, `Graduates/Jobseeker`, `Employer`, `Admin`, `Assessment`, and `Interview`.
   - Shared UI primitives live in `client/src/components/` and are reused across pages for inputs, cards, badges, dashboards, and PDF-style content blocks.

3. **Client state and route protection**
   - `AuthContext.jsx` is the main client-side state boundary for identity/session-aware behavior.
   - `ProtectedRoute.jsx` and `AdminRoute.jsx` enforce access control in the UI, separating public landing/auth pages from authenticated role-specific dashboards.

4. **Primary frontend workflows**
   - Job seekers manage profiles, resumes, saved jobs, applications, messages, and assessments.
   - Employers manage job posts, applicants, assessments, chat, and candidate ranking.
   - Admin pages cover users, jobs, reports, FAQs, interview scoring, and assessment management.
   - The app is therefore a multi-tenant career platform with distinct dashboards for each actor.

5. **Assessment and interview UX**
   - Two specialized front-end flows stand out: **assessments** and **interviews**.
   - The assessment UI includes instruction, agreement, violation warning, and taking/review screens.
   - The interview UI includes setup, camera/rules/agreement steps, live room, evaluation, and results screens, suggesting a guided session-based experience rather than a simple form flow.

6. **Backend API boundary**
   - The backend is structured in the usual Express layers: **routes → controllers → models/services**.
   - Route files define API surfaces by domain (`auth`, `job`, `application`, `assessment`, `interview`, `message`, `notification`, etc.).
   - Controllers contain the orchestration logic and coordinate persistence, side effects, and downstream services.

7. **Persistence and domain model**
   - MongoDB via Mongoose is the main system of record.
   - Core collections include users, jobs, applications, saved jobs, conversations, messages, assessments, interviews, employer settings, FAQs, and interview metadata.
   - This indicates a relational business domain modeled in document form, with several cross-entity workflows such as applications, chat, and interview history.

8. **Cross-cutting middleware and policy**
   - Middleware handles authentication, validation, upload handling, error mapping, and 404s.
   - This is the main boundary for request policy enforcement before business logic executes.
   - Error classes in `src/errors/` standardize API failures across controllers and middleware.

9. **Integrations and asynchronous side effects**
   - The backend includes several non-DB services: **Cloudinary** for media storage, **email delivery** for notifications/templates, and **Socket.io** for realtime messaging/updates.
   - These are likely triggered from controllers or helper utilities after domain events such as registration, application changes, assessment outcomes, or messaging.

10. **AI and document intelligence**
   - AI is a first-class subsystem, not an add-on.
   - `services/ai/` and `ollama.service.ts` point to local LLM orchestration through **Ollama**, including an interview-agent workflow.
   - `ocr.service.ts` and the README’s OCR feature indicate document verification flows for transcripts and permits, while `AISummaryGenerator.js` on the client supports resume/profile enrichment.

11. **Resume and document generation**
   - The client has a dedicated resume builder plus `ResumePDFx.jsx`, backed by a custom `pdfx` component set and theme utilities.
   - This suggests a structured PDF generation pipeline for resumes and possibly certificates or reports, with presentation components separated from the main app UI.

12. **External communication and notification flow**
   - Notifications are modeled as a backend concern with a dedicated route/controller pair and likely fed into both email and realtime channels.
   - Combined with sockets and message/conversation models, the system supports both persistent messaging and live presence-style interaction.

13. **Key architecture boundary to diagram**
   - The most important diagram boundary is between the **role-based React client** and the **domain/API backend**.
   - On the server side, the next boundaries are **HTTP routing**, **business orchestration**, **persistence in MongoDB**, and **side-effect services** such as AI, OCR, email, media storage, and realtime sockets.

Main entry points: [`new-sirbir/src/controllers`](https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/controllers) (Controllers), [`new-sirbir/src/routes`](https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/routes) (HTTP Routes), [`client/src/components`](https://github.com/mark20042/gradsync/tree/main/client/src/components) (Shared UI), [`client/src/pages/Auth`](https://github.com/mark20042/gradsync/tree/main/client/src/pages/Auth) (Auth Flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_landing["Landing Page<br/>public marketing<br/>[LandingPage.jsx]"]
  node_auth["Auth Flow<br/>signup/login"]
  node_jobseeker["Jobseeker UI<br/>dashboard/workflow"]
  node_employer["Employer UI<br/>dashboard/workflow"]
  node_admin["Admin UI<br/>back-office"]
  node_assessment["Assessment UI<br/>guided flow"]
  node_interview["Interview UI<br/>session flow"]
  node_ui_components["Shared UI<br/>component library"]
  node_auth_ctx(("Auth Context<br/>client state<br/>[AuthContext.jsx]"))
  node_ui_routes(("Route Guards<br/>access control"))
end

subgraph group_server["Express API"]
  node_server_api["API Server<br/>express app<br/>[app.ts]"]
  node_routes["HTTP Routes<br/>api surface"]
  node_controllers["Controllers<br/>orchestration"]
  node_middleware["Middleware<br/>policy layer"]
  node_models[("Mongoose Models<br/>data model")]
end

subgraph group_infra["Shared services"]
  node_ai{{"AI Services<br/>LLM orchestration"}}
  node_ocr["OCR Service<br/>document intelligence<br/>[ocr.service.ts]"]
  node_media["Media Storage<br/>cloudinary"]
  node_realtime(("Realtime Socket<br/>socket.io<br/>[socket.service.ts]"))
  node_email["Email Templates<br/>notifications"]
end

node_landing -->|"renders with"| node_ui_components
node_auth -->|"updates"| node_auth_ctx
node_auth -->|"protected by"| node_ui_routes
node_jobseeker -->|"uses"| node_ui_components
node_employer -->|"uses"| node_ui_components
node_admin -->|"uses"| node_ui_components
node_assessment -->|"uses"| node_ui_components
node_interview -->|"uses"| node_ui_components
node_ui_routes -->|"gates access to"| node_server_api
node_server_api -->|"mounts"| node_routes
node_routes -->|"delegates to"| node_controllers
node_controllers -->|"passes through"| node_middleware
node_controllers -->|"persists via"| node_models
node_controllers -->|"invokes"| node_ai
node_controllers -->|"uses"| node_ocr
node_controllers -->|"uploads to"| node_media
node_controllers -->|"emits events to"| node_realtime
node_controllers -->|"sends through"| node_email
node_models -->|"served by"| node_routes
node_assessment -->|"consumes assessment APIs"| node_routes
node_interview -->|"consumes interview APIs"| node_routes
node_jobseeker -->|"consumes job/app APIs"| node_routes
node_employer -->|"consumes employer APIs"| node_routes
node_admin -->|"consumes admin APIs"| node_routes

click node_landing "https://github.com/mark20042/gradsync/blob/main/client/src/pages/LandingPage/LandingPage.jsx"
click node_auth "https://github.com/mark20042/gradsync/tree/main/client/src/pages/Auth"
click node_jobseeker "https://github.com/mark20042/gradsync/tree/main/client/src/pages/Graduates/Jobseeker"
click node_employer "https://github.com/mark20042/gradsync/tree/main/client/src/pages/Employer"
click node_admin "https://github.com/mark20042/gradsync/tree/main/client/src/pages/Admin"
click node_assessment "https://github.com/mark20042/gradsync/tree/main/client/src/pages/Assessment"
click node_interview "https://github.com/mark20042/gradsync/tree/main/client/src/pages/Interview"
click node_ui_components "https://github.com/mark20042/gradsync/tree/main/client/src/components"
click node_auth_ctx "https://github.com/mark20042/gradsync/blob/main/client/src/context/AuthContext.jsx"
click node_ui_routes "https://github.com/mark20042/gradsync/tree/main/client/src/routes"
click node_server_api "https://github.com/mark20042/gradsync/blob/main/new-sirbir/src/app.ts"
click node_routes "https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/routes"
click node_controllers "https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/controllers"
click node_middleware "https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/middlewares"
click node_models "https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/models"
click node_ai "https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/services/ai"
click node_ocr "https://github.com/mark20042/gradsync/blob/main/new-sirbir/src/utils/ocr.service.ts"
click node_media "https://github.com/mark20042/gradsync/blob/main/new-sirbir/src/services/cloudinary.service.ts"
click node_realtime "https://github.com/mark20042/gradsync/blob/main/new-sirbir/src/services/socket.service.ts"
click node_email "https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/templates/email"

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_landing,node_auth,node_jobseeker,node_employer,node_admin,node_assessment,node_interview,node_ui_components,node_auth_ctx,node_ui_routes toneBlue
class node_server_api,node_routes,node_controllers,node_middleware,node_models toneAmber
class node_ai,node_ocr,node_media,node_realtime,node_email toneMint
```

## Components

### React client

Role-based UI, state, and workflow screens.

- [Landing Page](https://github.com/mark20042/gradsync/blob/main/client/src/pages/LandingPage/LandingPage.jsx): public marketing · Public site with feature, company, and job discovery sections. · `client/src/pages/LandingPage/LandingPage.jsx`
- [Auth Flow](https://github.com/mark20042/gradsync/tree/main/client/src/pages/Auth): signup/login · Login, signup, and profile setup for graduates and jobseekers. · `client/src/pages/Auth`
- [Jobseeker UI](https://github.com/mark20042/gradsync/tree/main/client/src/pages/Graduates/Jobseeker): dashboard/workflow · Profile, resume, jobs, applications, messages, and saved jobs. · `client/src/pages/Graduates/Jobseeker`
- [Employer UI](https://github.com/mark20042/gradsync/tree/main/client/src/pages/Employer): dashboard/workflow · Job posting, applicants, assessments, chat, and candidate ranking. · `client/src/pages/Employer`
- [Admin UI](https://github.com/mark20042/gradsync/tree/main/client/src/pages/Admin): back-office · User, job, report, FAQ, assessment, and interview administration. · `client/src/pages/Admin`
- [Assessment UI](https://github.com/mark20042/gradsync/tree/main/client/src/pages/Assessment): guided flow · Assessment instructions, agreement, warnings, taking, and review screens. · `client/src/pages/Assessment`
- [Interview UI](https://github.com/mark20042/gradsync/tree/main/client/src/pages/Interview): session flow · Setup, camera/rules, live room, evaluation, and results screens. · `client/src/pages/Interview`
- [Shared UI](https://github.com/mark20042/gradsync/tree/main/client/src/components): component library · Reusable inputs, cards, badges, charts, layout, and PDF-style blocks. · `client/src/components`
- [Auth Context](https://github.com/mark20042/gradsync/blob/main/client/src/context/AuthContext.jsx): client state · Session and identity state boundary for the frontend. · `client/src/context/AuthContext.jsx`
- [Route Guards](https://github.com/mark20042/gradsync/tree/main/client/src/routes): access control · Protected and admin-only route gating in the client. · `client/src/routes`

### Express API

HTTP API, domain logic, persistence, and side effects.

- [API Server](https://github.com/mark20042/gradsync/blob/main/new-sirbir/src/app.ts): express app · Main TypeScript/Express application bootstrap and server entrypoint. · `new-sirbir/src/app.ts`
- [HTTP Routes](https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/routes): api surface · Domain route layer for auth, jobs, applications, assessments, interviews, messaging, notifications, and admin. · `new-sirbir/src/routes`
- [Controllers](https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/controllers): orchestration · Request orchestration, business coordination, and response shaping. · `new-sirbir/src/controllers`
- [Middleware](https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/middlewares): policy layer · Authentication, validation, upload handling, error mapping, and 404 handling. · `new-sirbir/src/middlewares`
- [Mongoose Models](https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/models): data model · Core collections for users, jobs, applications, conversations, assessments, interviews, and settings. · `new-sirbir/src/models`

### Shared services

Cross-cutting infrastructure and external integrations.

- [AI Services](https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/services/ai): LLM orchestration · Ollama-based AI workflows, interview agent logic, and AI endpoints. · `new-sirbir/src/services/ai`
- [OCR Service](https://github.com/mark20042/gradsync/blob/main/new-sirbir/src/utils/ocr.service.ts): document intelligence · Document extraction and verification support for uploaded records. · `new-sirbir/src/utils/ocr.service.ts`
- [Media Storage](https://github.com/mark20042/gradsync/blob/main/new-sirbir/src/services/cloudinary.service.ts): cloudinary · Upload and asset storage integration for media handling. · `new-sirbir/src/services/cloudinary.service.ts`
- [Realtime Socket](https://github.com/mark20042/gradsync/blob/main/new-sirbir/src/services/socket.service.ts): socket.io · Live messaging and event delivery for chat and updates. · `new-sirbir/src/services/socket.service.ts`
- [Email Templates](https://github.com/mark20042/gradsync/tree/main/new-sirbir/src/templates/email): notifications · Transactional email templates and delivery helpers for verification, approvals, interviews, and rejections. · `new-sirbir/src/templates/email`

## Connections

- Landing Page → Shared UI: renders with
- Auth Flow → Auth Context: updates
- Auth Flow → Route Guards: protected by
- Jobseeker UI → Shared UI: uses
- Employer UI → Shared UI: uses
- Admin UI → Shared UI: uses
- Assessment UI → Shared UI: uses
- Interview UI → Shared UI: uses
- Route Guards → API Server: gates access to
- API Server → HTTP Routes: mounts
- HTTP Routes → Controllers: delegates to
- Controllers → Middleware: passes through
- Controllers → Mongoose Models: persists via
- Controllers → AI Services: invokes
- Controllers → OCR Service: uses
- Controllers → Media Storage: uploads to
- Controllers → Realtime Socket: emits events to
- Controllers → Email Templates: sends through
- Mongoose Models → HTTP Routes: served by
- Assessment UI → HTTP Routes: consumes assessment APIs
- Interview UI → HTTP Routes: consumes interview APIs
- Jobseeker UI → HTTP Routes: consumes job/app APIs
- Employer UI → HTTP Routes: consumes employer APIs
- Admin UI → HTTP Routes: consumes admin APIs
