# yashdew/assessor architecture

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

- Interactive diagram: https://gitdiagram.com/yashdew/assessor
- Repository: https://github.com/yashdew/assessor

## Overview

1. **Overall shape**
   - Assessor is a two-tier resume analysis app: a **Next.js frontend** for recruiter/candidate interaction and a **Flask backend** for resume parsing/extraction.
   - The system is largely **stateless**: files are uploaded, parsed, and returned as structured JSON rather than being persisted in a database.

2. **Frontend boundary**
   - The `frontend/` directory is the user interface layer.
   - It owns upload forms, search, tabs, accordion views, modals, loaders, and applicant/job presentation components.
   - `utils/contexts.js` and `utils/store.js` indicate centralized client-side state management for the UI.

3. **Frontend data flow**
   - Users interact with components like `FileUpload`, `FormUpload`, `JobDescription`, and `SearchBar`.
   - The UI then either calls backend endpoints or uses local dummy data to populate applicant/job views.
   - Filtering and ranking behavior is pushed into browser-side helpers such as `filterApplicants.js` and `filterJobs.js`.

4. **Backend parsing service**
   - The `api/` directory is the analysis engine, built around **Flask**.
   - `run.py` is the server entry point, and `Procfile` suggests the service is designed for PaaS deployment.
   - The public API surface is centered on a resume upload endpoint described in the README as `POST /api/v1/postResume`.

5. **Resume extraction subsystem**
   - `api/resume/extraction/resumeextraction.py` and `utils.py` contain the core parsing logic.
   - This layer converts uploaded PDF resumes into structured fields such as personal details, skills, education, experience, projects, achievements, links, and hobbies.
   - The README’s example response shows the backend returns one normalized JSON object per resume.

6. **Text/ML dependency boundary**
   - `requirements.txt` and `nltk.txt` show the backend depends on Python NLP tooling, especially **Pyresparser** and **NLTK**.
   - Architecturally, this means parsing is not just file upload handling; it includes text extraction, entity detection, and resume field inference.

7. **Error and fallback handling**
   - `api/resume/error/error.py` provides a dedicated error path for failed parsing or invalid input.
   - `api/resume/dummy/dummyapi.py` indicates a mock or placeholder backend response path, likely used during development or demo mode when real parsing is unavailable.

8. **Mock/demo support in the frontend**
   - `frontend/utils/dummyAPI.js` and the Next.js `pages/api/` routes (`applicants.js`, `jobs.js`, `hello.js`) suggest the frontend can operate with local mock data.
   - This creates a second data source besides the Flask API, useful for UI development and demos without the parser running.

9. **UI composition and display model**
   - `Applicant.jsx`, `Accordion.jsx`, `Tabs.jsx`, `Modal.js`, `Loader.jsx`, and `Links.jsx` are presentation components for showing parsed resume content and supporting recruiter workflows.
   - The UI is structured to display a list of applicants/jobs and then drill into detailed extracted resume sections.

10. **Sample data and test assets**
   - The `Sample Resume/` folder contains real PDF examples and a text sample, which are likely used to validate extraction behavior.
   - These files are part of the repo’s test/demo content, not runtime state.

11. **Primary integration point**
   - The key contract between frontend and backend is the resume JSON schema returned by the Flask API.
   - Everything downstream in the UI depends on that schema: applicant cards, skill matching, search/filtering, and detailed resume views.

12. **What is not present**
   - There is no visible database layer, authentication system, or external message queue.
   - That keeps the architecture simple: upload/request in, parsed JSON out, UI rendering and filtering on top.

Main entry points: [`frontend/pages/index.js`](https://github.com/yashdew/assessor/blob/main/frontend/pages/index.js) (UI shell), [`api/resume/routes.py`](https://github.com/yashdew/assessor/blob/main/api/resume/routes.py) (API routes), [`frontend/components/FileUpload.jsx`](https://github.com/yashdew/assessor/blob/main/frontend/components/FileUpload.jsx) (Upload forms), [`api/resume/extraction/resumeextraction.py`](https://github.com/yashdew/assessor/blob/main/api/resume/extraction/resumeextraction.py) (Extractor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_shell["UI shell<br/>next app<br/>[index.js]"]
  node_ui_state["State layer<br/>client state<br/>[store.js]"]
  node_ui_upload["Upload forms<br/>input widgets<br/>[FileUpload.jsx]"]
  node_ui_search["Search tools<br/>filter widgets<br/>[SearchBar.jsx]"]
  node_ui_profiles["Applicant views<br/>presentation<br/>[Applicant.jsx]"]
  node_ui_jobs["Job views<br/>presentation<br/>[JobDescription.js]"]
  node_ui_panels["Detail panels<br/>ui widgets<br/>[Accordion.jsx]"]
  node_ui_mock["Mock data<br/>demo data<br/>[dummyAPI.js]"]
  node_ui_api_routes["API routes<br/>next api<br/>[applicants.js]"]
  node_ui_filters["Filters<br/>helpers"]
end

subgraph group_backend["Backend"]
  node_server_entry["Server entry<br/>flask app<br/>[run.py]"]
  node_server_routes["API routes<br/>flask routes<br/>[routes.py]"]
  node_extractor["Extractor<br/>resume parser"]
  node_extract_utils["Parse utils<br/>nlu helpers<br/>[utils.py]"]
  node_error_path["Error path<br/>error handling<br/>[error.py]"]
  node_dummy_backend["Dummy API<br/>fallback service<br/>[dummyapi.py]"]
end

subgraph group_assets["Samples"]
  node_sample_resumes["Sample resumes<br/>pdf samples"]
end

node_ui_shell -->|"renders"| node_ui_upload
node_ui_shell -->|"renders"| node_ui_search
node_ui_shell -->|"renders"| node_ui_profiles
node_ui_shell -->|"renders"| node_ui_jobs
node_ui_shell -->|"uses"| node_ui_panels
node_ui_state -->|"feeds"| node_ui_shell
node_ui_search -->|"applies"| node_ui_filters
node_ui_profiles -->|"reads"| node_ui_state
node_ui_jobs -->|"reads"| node_ui_state
node_ui_upload -->|"submits"| node_ui_api_routes
node_ui_upload -->|"submits"| node_server_routes
node_ui_mock -->|"backs"| node_ui_api_routes
node_ui_api_routes -->|"serves"| node_ui_shell
node_server_entry -->|"starts"| node_server_routes
node_server_routes -->|"invokes"| node_extractor
node_extractor -->|"uses"| node_extract_utils
node_server_routes -->|"fails to"| node_error_path
node_server_routes -.->|"can fallback"| node_dummy_backend
node_extractor -.->|"validated by"| node_sample_resumes
node_server_routes -->|"returns JSON"| node_ui_profiles
node_server_routes -->|"returns JSON"| node_ui_filters

click node_ui_shell "https://github.com/yashdew/assessor/blob/main/frontend/pages/index.js"
click node_ui_state "https://github.com/yashdew/assessor/blob/main/frontend/utils/store.js"
click node_ui_upload "https://github.com/yashdew/assessor/blob/main/frontend/components/FileUpload.jsx"
click node_ui_search "https://github.com/yashdew/assessor/blob/main/frontend/components/SearchBar.jsx"
click node_ui_profiles "https://github.com/yashdew/assessor/blob/main/frontend/components/Applicant.jsx"
click node_ui_jobs "https://github.com/yashdew/assessor/blob/main/frontend/components/JobDescription.js"
click node_ui_panels "https://github.com/yashdew/assessor/blob/main/frontend/components/Accordion.jsx"
click node_ui_mock "https://github.com/yashdew/assessor/blob/main/frontend/utils/dummyAPI.js"
click node_ui_api_routes "https://github.com/yashdew/assessor/blob/main/frontend/pages/api/applicants.js"
click node_ui_filters "https://github.com/yashdew/assessor/blob/main/frontend/utils/filterApplicants.js"
click node_server_entry "https://github.com/yashdew/assessor/blob/main/api/run.py"
click node_server_routes "https://github.com/yashdew/assessor/blob/main/api/resume/routes.py"
click node_extractor "https://github.com/yashdew/assessor/blob/main/api/resume/extraction/resumeextraction.py"
click node_extract_utils "https://github.com/yashdew/assessor/blob/main/api/resume/extraction/utils.py"
click node_error_path "https://github.com/yashdew/assessor/blob/main/api/resume/error/error.py"
click node_dummy_backend "https://github.com/yashdew/assessor/blob/main/api/resume/dummy/dummyapi.py"
click node_sample_resumes "https://github.com/yashdew/assessor/blob/main/Sample Resume/Sameer Kolpekwar Resume-1.pdf"

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_ui_shell,node_ui_state,node_ui_upload,node_ui_search,node_ui_profiles,node_ui_jobs,node_ui_panels,node_ui_mock,node_ui_api_routes,node_ui_filters toneBlue
class node_server_entry,node_server_routes,node_extractor,node_extract_utils,node_error_path,node_dummy_backend toneAmber
class node_sample_resumes toneMint
```

## Components

### Frontend

Next.js UI for uploads, search, applicant/job browsing, and client-side state.

- [UI shell](https://github.com/yashdew/assessor/blob/main/frontend/pages/index.js): next app · Next.js app entry and page composition. · `frontend/pages/index.js`
- [State layer](https://github.com/yashdew/assessor/blob/main/frontend/utils/store.js): client state · Shared UI context and store for browser-side app state. · `frontend/utils/store.js`
- [Upload forms](https://github.com/yashdew/assessor/blob/main/frontend/components/FileUpload.jsx): input widgets · Resume and form upload components. · `frontend/components/FileUpload.jsx`
- [Search tools](https://github.com/yashdew/assessor/blob/main/frontend/components/SearchBar.jsx): filter widgets · Search and filtering controls for applicants and jobs. · `frontend/components/SearchBar.jsx`
- [Applicant views](https://github.com/yashdew/assessor/blob/main/frontend/components/Applicant.jsx): presentation · Applicant cards and detailed resume section rendering. · `frontend/components/Applicant.jsx`
- [Job views](https://github.com/yashdew/assessor/blob/main/frontend/components/JobDescription.js): presentation · Job description and job listing display components. · `frontend/components/JobDescription.js`
- [Detail panels](https://github.com/yashdew/assessor/blob/main/frontend/components/Accordion.jsx): ui widgets · Accordion, tabs, modal, loader, and links used to drill into parsed content. · `frontend/components/Accordion.jsx`
- [Mock data](https://github.com/yashdew/assessor/blob/main/frontend/utils/dummyAPI.js): demo data · Frontend fallback data and local API shims for development and demos. · `frontend/utils/dummyAPI.js`
- [API routes](https://github.com/yashdew/assessor/blob/main/frontend/pages/api/applicants.js): next api · Local Next.js API endpoints for demo data and health checks. · `frontend/pages/api/applicants.js`
- [Filters](https://github.com/yashdew/assessor/blob/main/frontend/utils/filterApplicants.js): helpers · Browser-side applicant and job filtering logic. · `frontend/utils/filterApplicants.js`

### Backend

Flask resume parsing service and its extraction/error paths.

- [Server entry](https://github.com/yashdew/assessor/blob/main/api/run.py): flask app · Flask application startup and deployment entry point. · `api/run.py`
- [API routes](https://github.com/yashdew/assessor/blob/main/api/resume/routes.py): flask routes · Public resume upload endpoint and request dispatch. · `api/resume/routes.py`
- [Extractor](https://github.com/yashdew/assessor/blob/main/api/resume/extraction/resumeextraction.py): resume parser · Core resume parsing and field extraction pipeline. · `api/resume/extraction/resumeextraction.py`
- [Parse utils](https://github.com/yashdew/assessor/blob/main/api/resume/extraction/utils.py): nlu helpers · Supporting text extraction and normalization utilities. · `api/resume/extraction/utils.py`
- [Error path](https://github.com/yashdew/assessor/blob/main/api/resume/error/error.py): error handling · Dedicated handling for invalid or failed parsing requests. · `api/resume/error/error.py`
- [Dummy API](https://github.com/yashdew/assessor/blob/main/api/resume/dummy/dummyapi.py): fallback service · Mock backend response path for development or demo mode. · `api/resume/dummy/dummyapi.py`

### Samples

Demo resumes and sample text used for validation and showcasing extraction.

- [Sample resumes](https://github.com/yashdew/assessor/blob/HEAD/Sample%20Resume/Sameer%20Kolpekwar%20Resume-1.pdf): pdf samples · Example resumes and text used as demo inputs and extraction references. · `Sample Resume/Sameer Kolpekwar Resume-1.pdf`

## Connections

- UI shell → Upload forms: renders · Main page composes upload workflow.
- UI shell → Search tools: renders · Main page exposes search and filtering controls.
- UI shell → Applicant views: renders · Main page shows applicant cards and detail views.
- UI shell → Job views: renders · Main page shows job listings and descriptions.
- UI shell → Detail panels: uses · Shared disclosure and display widgets support the UI.
- State layer → UI shell: feeds · Centralized browser state drives page composition.
- Search tools → Filters: applies · Search controls invoke filtering helpers.
- Applicant views → State layer: reads · Applicant views consume shared UI state.
- Job views → State layer: reads · Job views consume shared UI state.
- Upload forms → API routes: submits · Local upload flows can use Next.js API endpoints.
- Upload forms → API routes: submits · Primary upload flow sends resumes to Flask.
- Mock data → API routes: backs · Mock layer supports local API route data.
- API routes → UI shell: serves · Frontend API routes provide demo data to the UI.
- Server entry → API routes: starts · Flask entry point mounts the resume API.
- API routes → Extractor: invokes · Upload endpoint delegates parsing to the extraction pipeline.
- Extractor → Parse utils: uses · Parser relies on NLP and normalization helpers.
- API routes → Error path: fails to · Invalid inputs and parse failures follow the error path.
- API routes → Dummy API: can fallback · Development or demo mode may return mock responses.
- Extractor → Sample resumes: validated by · Sample PDFs provide representative input for extraction behavior.
- API routes → Applicant views: returns JSON · Backend resume schema feeds applicant rendering.
- API routes → Filters: returns JSON · Structured resume data supports client-side filtering and ranking.