How amansinghy30/ai-resume-platform works
1. Repository shape
- This is a split-client/server application. The client/ folder is a React + TypeScript SPA, and server/ is an Express/Node API with MongoDB persistence.
- The root also contains a saved n8n workflow export (Job Matching Workflow (1).json), which is part of the automation layer rather than the main app runtime.
2. Primary user-facing app
- The frontend is centered around a hiring workflow UI: landing, auth, dashboard, jobs, candidates, rankings, shortlisted, uploads, activity, and detail pages.
- Routes are likely protected after login via ProtectedRoute, with public entry points for Landing, Login, and Register.
3. Frontend state and layout boundaries
- AuthContext owns session/login state; ThemeContext owns dark/light mode persistence.
- The UI is composed from reusable presentational pieces in components/ such as tables, cards, badges, score widgets, nav/sidebar/layout shells, forms, and loading states.
- Page components in pages/ assemble these into feature screens rather than containing low-level network logic.
4. Frontend data access layer
- Network calls are isolated in client/src/services/, with separate service modules for auth, candidates, jobs, dashboard, and activity.
- This creates a clean boundary between the UI and the backend API, making the pages thin consumers of domain-specific endpoints.
5. Backend API structure
- The server is organized by domain: auth, candidates, jobs, dashboard, activity, and ai.
- Controllers contain the business logic, routes expose REST endpoints, and middleware handles cross-cutting concerns like JWT auth, file uploads, error handling, and 404s.
6. Data model boundary
- MongoDB/Mongoose models represent the core entities: User, Job, Candidate, and ActivityLog.
- These collections are the system of record for candidate intake, job definitions, scoring results, and audit/activity history.
7. Resume ingestion and parsing pipeline
- PDF resume uploads enter through the backend upload middleware (multer-style handling), then are parsed with utilities such as pdfParser, contactExtractor, skillExtractor, and backfillParsing.
- The parsed text is turned into structured candidate data before being stored or further analyzed, which is the main ingestion boundary in the system.
8. AI scoring and enrichment path
- The server’s AI utilities (aiClient, prompts, parseJSON) indicate a structured prompt/response pipeline around Gemini AI.
- Candidate data is transformed into richer outputs: match score, strengths, concerns, skill matches, missing requirements, and likely shortlist/reject decisions.
- The aiController and ai route form the API boundary for this scoring/enrichment flow.
9. Automation and external workflow integration
- The project integrates with n8n through n8nClient and the exported workflow JSON, suggesting an asynchronous automation layer outside the core API.
- The README describes conditional branching for acceptance/rejection emails, so email outreach is handled as an external workflow rather than inside the main Express request path.
10. Activity logging and event visibility
- Activity is treated as a first-class subsystem: activityLogger, ActivityLog model, and activity routes support a feed in the UI.
- MongoDB Change Streams are used to detect document updates and emit log entries automatically, so auditing is event-driven rather than manually written at every UI action.
11. Main end-to-end flow
- A typical flow is: user logs in → uploads a resume → backend parses PDF → AI scores candidate against a selected job → candidate record is updated → n8n may send email → Change Stream writes an activity event → frontend refreshes dashboard/activity/candidate views.
- That makes the system a pipeline from file ingestion to structured candidate intelligence and operational follow-up.
12. Operational/support pieces
- seed.js and migrateUserData.js suggest setup and maintenance scripts for initial data and schema evolution.
- dashboardController and dashboardService indicate an aggregated metrics layer for totals, shortlisted counts, pending review, and active jobs, rather than computing everything in the client.
Main entry points: index.js API entry · Candidate.js Data models · candidateController.js Candidate API · Dashboard.tsx Work pages
Components 21
Client
React + TypeScript SPA for hiring workflow and candidate management.
- App shell · Top-level client routing and application composition.
client/src/App.tsx - Auth state · Session and login state for protected areas.
client/src/context/AuthContext.tsx - Theme state · Light/dark theme persistence and toggling.
client/src/context/ThemeContext.tsx - Public pages · Landing, login, and registration entry points.
client/src/pages/Landing.tsx - Work pages · Dashboard, jobs, candidates, rankings, shortlisted, upload, activity, and detail views.
client/src/pages/Dashboard.tsx - Protected route · Route gate for authenticated application areas.
client/src/components/ProtectedRoute.tsx - Layout UI · Navbar, sidebar, and layout scaffolding for the SPA.
client/src/components/Layout.tsx - Feature UI · Tables, cards, badges, search, filters, scores, forms, and loading states.
client/src/components/CandidateTable.tsx - Client API · Domain-specific client calls for auth, candidates, jobs, dashboard, and activity.
client/src/services/api.ts
Server
Express API with MongoDB persistence, AI scoring, and activity logging.
- API entry · Server bootstrap and middleware wiring.
server/index.js - Auth API · Login, registration, and JWT session handling.
server/controllers/authController.js - Candidate API · Candidate intake, retrieval, and scoring-related operations.
server/controllers/candidateController.js - Jobs API · Job definitions and job detail endpoints.
server/controllers/jobController.js - Dashboard API · Aggregated counts, shortlist metrics, and review status data.
server/controllers/dashboardController.js - Activity API · Activity feed endpoints for audit and visibility.
server/routes/activity.js - AI API · Candidate enrichment and scoring endpoints.
server/controllers/aiController.js - Upload pipeline · Resume upload handling and PDF-to-text parsing boundary.
server/middleware/upload.js - AI pipeline · Prompting, Gemini client, and JSON response parsing for candidate enrichment.
server/utils/aiClient.js - Activity system · Activity log writer and change-stream driven event visibility.
server/utils/activityLogger.js - Data models · User, Job, Candidate, and ActivityLog collections.
server/models/Candidate.js
Automation
External workflow export and integration layer for follow-up actions.
- n8n workflow · Saved workflow export for branching follow-up automation.
Job Matching Workflow (1).json
Connections 25
- App shell → Public pages: routes to · Public entry screens are mounted from the app router.
- App shell → Protected route: guards · Authenticated areas are wrapped by the protected route boundary.
- Protected route → Work pages: allows · Protected navigation leads into the main app screens.
- Auth state → Protected route: drives access · Session state determines whether protected routes render.
- Theme state → Layout UI: styles · Theme state affects shared UI shell rendering.
- Work pages → Layout UI: compose with · Feature screens are assembled inside the common layout.
- Work pages → Feature UI: use · Pages rely on reusable presentational widgets.
- Feature UI → Client API: fetch via · UI components consume data through service modules.
- Client API → API entry: calls · Client requests are sent to the Express API.
- API entry → Auth API: mounts · Authentication routes and controller logic are exposed here.
- API entry → Candidate API: mounts · Candidate domain endpoints are exposed here.
- API entry → Jobs API: mounts · Job domain endpoints are exposed here.
- API entry → Dashboard API: mounts · Dashboard aggregation endpoints are exposed here.
- API entry → Activity API: mounts · Activity feed endpoints are exposed here.
- API entry → AI API: mounts · AI scoring and enrichment endpoints are exposed here.
- Candidate API → Upload pipeline: ingests · Resume uploads are parsed before candidate records are updated.
- Candidate API → AI pipeline: scores with · Candidate data is enriched through the AI prompt/response pipeline.
- Candidate API → Data models: persists to · Candidate records are stored in MongoDB.
- Auth API → Data models: reads/writes · User accounts are managed in MongoDB.
- Jobs API → Data models: reads/writes · Job definitions are stored in MongoDB.
- Dashboard API → Data models: aggregates · Dashboard metrics are computed from stored domain records.
- Activity API → Activity system: reads · Feed entries come from the logging subsystem.
- Activity system → Data models: writes · Activity events are persisted as log documents.
- AI pipeline → n8n workflow: branches to · Enrichment can hand off to external automation for follow-up actions.
- Activity system → n8n workflow: triggers · Automation may emit outreach or status-change follow-ups.