How mark20042/gradsync works
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: controllers Controllers · routes HTTP Routes · components Shared UI · Auth Auth Flow
Components 20
React client
Role-based UI, state, and workflow screens.
- Landing Page · Public site with feature, company, and job discovery sections.
client/src/pages/LandingPage/LandingPage.jsx - Auth Flow · Login, signup, and profile setup for graduates and jobseekers.
client/src/pages/Auth - Jobseeker UI · Profile, resume, jobs, applications, messages, and saved jobs.
client/src/pages/Graduates/Jobseeker - Employer UI · Job posting, applicants, assessments, chat, and candidate ranking.
client/src/pages/Employer - Admin UI · User, job, report, FAQ, assessment, and interview administration.
client/src/pages/Admin - Assessment UI · Assessment instructions, agreement, warnings, taking, and review screens.
client/src/pages/Assessment - Interview UI · Setup, camera/rules, live room, evaluation, and results screens.
client/src/pages/Interview - Shared UI · Reusable inputs, cards, badges, charts, layout, and PDF-style blocks.
client/src/components - Auth Context · Session and identity state boundary for the frontend.
client/src/context/AuthContext.jsx - Route Guards · Protected and admin-only route gating in the client.
client/src/routes
Express API
HTTP API, domain logic, persistence, and side effects.
- API Server · Main TypeScript/Express application bootstrap and server entrypoint.
new-sirbir/src/app.ts - HTTP Routes · Domain route layer for auth, jobs, applications, assessments, interviews, messaging, notifications, and admin.
new-sirbir/src/routes - Controllers · Request orchestration, business coordination, and response shaping.
new-sirbir/src/controllers - Middleware · Authentication, validation, upload handling, error mapping, and 404 handling.
new-sirbir/src/middlewares - Mongoose Models · 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 · Ollama-based AI workflows, interview agent logic, and AI endpoints.
new-sirbir/src/services/ai - OCR Service · Document extraction and verification support for uploaded records.
new-sirbir/src/utils/ocr.service.ts - Media Storage · Upload and asset storage integration for media handling.
new-sirbir/src/services/cloudinary.service.ts - Realtime Socket · Live messaging and event delivery for chat and updates.
new-sirbir/src/services/socket.service.ts - Email Templates · Transactional email templates and delivery helpers for verification, approvals, interviews, and rejections.
new-sirbir/src/templates/email
Connections 24
- 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