# sahrior/cvision-ai architecture

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

- Interactive diagram: https://gitdiagram.com/sahrior/cvision-ai
- Repository: https://github.com/sahrior/cvision-ai

## Overview

1. **Overall shape**
   - This is a **React Router full-stack app** using the React Router SSR template.
   - The architecture is route-driven: each page lives in `app/routes/*`, with shared layout and shell code in `app/root.tsx`.
   - The repo is TypeScript-first and built with **Vite**; the README indicates the build produces separate client and server outputs.

2. **Product/domain focus**
   - The file names strongly suggest a **resume upload + ATS scoring/analysis workflow**.
   - The main user journey appears to be: authenticate, upload a resume, view an analyzed resume report, and optionally wipe/reset stored data.

3. **Route layer as the primary boundary**
   - `app/routes/home.tsx`, `Upload.tsx`, `resume.tsx`, `auth.tsx`, and `wipe.tsx` are the main application entry points.
   - In React Router terms, these route modules are where data loading, mutations, and page-specific composition likely happen.
   - `app/routes.ts` defines the route structure and navigation boundaries.

4. **Shared UI composition**
   - The `app/components` folder contains the reusable presentation pieces for the resume-analysis UI:
     - `FileUploader` for selecting/submitting resume files
     - `ResumeCard`, `Summary`, `Details` for report display
     - `ATS`, `ScoreBadge`, `ScoreCircle`, `ScoreGauge` for scoring visualization
     - `Accordion` for expandable sections
     - `Navbar` for top-level navigation
   - These are mostly view components, keeping the page routes thin and focused on orchestration.

5. **Processing and file transformation**
   - `app/lib/pdf2img.ts` is an important processing boundary: it suggests uploaded PDF resumes are converted to images, likely for previewing or analysis.
   - This implies the app handles both raw document input and a derived visual representation before rendering the report.

6. **External service integration**
   - `app/lib/puter.ts` plus `types/puter.d.ts` indicate a dedicated integration layer for **Puter**.
   - That makes Puter a likely external dependency for storage, auth, or backend-like capabilities.
   - Architecturally, this is the main seam between the app’s UI/routes and an external persistence/auth service.

7. **Cross-cutting utilities and domain constants**
   - `app/lib/utils.ts`, `constants/index.ts`, and `types/index.d.ts` centralize shared logic, constants, and domain typings.
   - This keeps route modules and components from duplicating formatting, scoring thresholds, labels, or data shapes.

8. **Authentication and reset flows**
   - The presence of `auth.tsx` and `wipe.tsx` suggests the app supports session establishment and a full data reset path.
   - These are likely side-effect-heavy routes/mutations rather than purely presentational screens.

9. **Static assets and branding**
   - `public/icons` and `public/images` hold static assets used by the UI.
   - `app/app.css` provides app-wide styling, with the README noting TailwindCSS is configured in the template.

10. **Runtime and deployment boundary**
   - The project is designed to run both locally with HMR via Vite and in production as a Node-based SSR app.
   - The `Dockerfile` and `.dockerignore` show first-class container deployment support, matching the README’s Docker deployment path.

11. **How the data likely flows**
   - User interaction starts in a route page, usually via `FileUploader`.
   - The uploaded resume is processed through route-level logic and `pdf2img` as needed.
   - App state/report data is then rendered by the scoring and summary components.
   - Persistent state or user/session data likely goes through the Puter integration layer.
   - `wipe` provides the cleanup path to clear that stored state.

12. **Architecture summary for diagramming**
   - Draw this as a **route-centric SSR React app** with:
     - a route/layout layer
     - a reusable component layer
     - a small processing/util layer
     - an external Puter integration boundary
     - static assets and deployment/runtime packaging around it
   - The dominant domain flow is **resume upload → processing/scoring → report display → optional reset**.

Main entry points: [`app/routes/resume.tsx`](https://github.com/sahrior/cvision-ai/blob/main/app/routes/resume.tsx) (Resume report), [`app/routes.ts`](https://github.com/sahrior/cvision-ai/blob/main/app/routes.ts) (Route map), [`app/routes/Upload.tsx`](https://github.com/sahrior/cvision-ai/blob/main/app/routes/Upload.tsx) (Upload), [`app/root.tsx`](https://github.com/sahrior/cvision-ai/blob/main/app/root.tsx) (Root shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Shell"]
  node_node_root["Root shell<br/>SSR entry<br/>[root.tsx]"]
  node_node_routes["Route map<br/>router config<br/>[routes.ts]"]
  node_node_navbar["Navbar<br/>layout component<br/>[Navbar.tsx]"]
end

subgraph group_group_domain["Resume Workflow"]
  node_node_home["Home<br/>route page<br/>[home.tsx]"]
  node_node_upload["Upload<br/>route page<br/>[Upload.tsx]"]
  node_node_resume["Resume report<br/>route page<br/>[resume.tsx]"]
  node_node_auth["Auth<br/>route page<br/>[auth.tsx]"]
  node_node_wipe["Wipe<br/>route action<br/>[wipe.tsx]"]
  node_node_uploader["File uploader<br/>input component<br/>[FileUploader.tsx]"]
  node_node_report["Report card<br/>display component<br/>[ResumeCard.tsx]"]
  node_node_summary["Summary<br/>report component<br/>[Summary.tsx]"]
  node_node_details["Details<br/>report component<br/>[Details.tsx]"]
  node_node_ats(("ATS score<br/>scoring component<br/>[ATS.tsx]"))
  node_node_scores(("Score widgets<br/>visualization set<br/>[ScoreBadge.tsx]"))
  node_node_accordion["Accordion<br/>ui component<br/>[Accordion.tsx]"]
end

subgraph group_group_lib["Shared Logic"]
  node_node_pdf2img["PDF to image<br/>processing lib<br/>[pdf2img.ts]"]
  node_node_puter["Puter bridge<br/>integration lib<br/>[puter.ts]"]
  node_node_utils["Utilities<br/>shared helpers<br/>[utils.ts]"]
  node_node_constants["Constants<br/>domain config<br/>[index.ts]"]
  node_node_types["Types<br/>type defs<br/>[index.d.ts]"]
  node_node_puter_types["Puter types<br/>service types<br/>[puter.d.ts]"]
end

subgraph group_group_runtime["Runtime & Assets"]
  node_node_styles["App styles<br/>stylesheet<br/>[app.css]"]
  node_node_public[("Static assets")]
  node_node_build["Build setup<br/>tooling<br/>[vite.config.ts]"]
end

node_node_routes -->|"mounts"| node_node_root
node_node_root -->|"renders"| node_node_navbar
node_node_routes -->|"includes"| node_node_home
node_node_routes -->|"includes"| node_node_upload
node_node_routes -->|"includes"| node_node_resume
node_node_routes -->|"includes"| node_node_auth
node_node_routes -->|"includes"| node_node_wipe
node_node_upload -->|"uses"| node_node_uploader
node_node_upload -->|"processes"| node_node_pdf2img
node_node_upload -->|"persists"| node_node_puter
node_node_resume -->|"renders"| node_node_report
node_node_resume -->|"renders"| node_node_summary
node_node_resume -->|"renders"| node_node_details
node_node_resume -->|"shows"| node_node_ats
node_node_resume -->|"visualizes"| node_node_scores
node_node_resume -->|"expands"| node_node_accordion
node_node_auth -->|"authenticates"| node_node_puter
node_node_wipe -->|"clears"| node_node_puter
node_node_upload -->|"shares"| node_node_utils
node_node_resume -->|"shares"| node_node_utils
node_node_resume -->|"uses"| node_node_constants
node_node_upload -->|"types"| node_node_types
node_node_resume -->|"types"| node_node_types
node_node_puter -->|"typed by"| node_node_puter_types
node_node_root -->|"loads"| node_node_styles
node_node_root -->|"references"| node_node_public
node_node_build -.->|"builds"| node_node_root
node_node_build -.->|"builds"| node_node_routes

click node_node_root "https://github.com/sahrior/cvision-ai/blob/main/app/root.tsx"
click node_node_routes "https://github.com/sahrior/cvision-ai/blob/main/app/routes.ts"
click node_node_home "https://github.com/sahrior/cvision-ai/blob/main/app/routes/home.tsx"
click node_node_upload "https://github.com/sahrior/cvision-ai/blob/main/app/routes/Upload.tsx"
click node_node_resume "https://github.com/sahrior/cvision-ai/blob/main/app/routes/resume.tsx"
click node_node_auth "https://github.com/sahrior/cvision-ai/blob/main/app/routes/auth.tsx"
click node_node_wipe "https://github.com/sahrior/cvision-ai/blob/main/app/routes/wipe.tsx"
click node_node_navbar "https://github.com/sahrior/cvision-ai/blob/main/app/components/Navbar.tsx"
click node_node_uploader "https://github.com/sahrior/cvision-ai/blob/main/app/components/FileUploader.tsx"
click node_node_report "https://github.com/sahrior/cvision-ai/blob/main/app/components/ResumeCard.tsx"
click node_node_summary "https://github.com/sahrior/cvision-ai/blob/main/app/components/Summary.tsx"
click node_node_details "https://github.com/sahrior/cvision-ai/blob/main/app/components/Details.tsx"
click node_node_ats "https://github.com/sahrior/cvision-ai/blob/main/app/components/ATS.tsx"
click node_node_scores "https://github.com/sahrior/cvision-ai/blob/main/app/components/ScoreBadge.tsx"
click node_node_accordion "https://github.com/sahrior/cvision-ai/blob/main/app/components/Accordion.tsx"
click node_node_pdf2img "https://github.com/sahrior/cvision-ai/blob/main/app/lib/pdf2img.ts"
click node_node_puter "https://github.com/sahrior/cvision-ai/blob/main/app/lib/puter.ts"
click node_node_utils "https://github.com/sahrior/cvision-ai/blob/main/app/lib/utils.ts"
click node_node_constants "https://github.com/sahrior/cvision-ai/blob/main/constants/index.ts"
click node_node_types "https://github.com/sahrior/cvision-ai/blob/main/types/index.d.ts"
click node_node_puter_types "https://github.com/sahrior/cvision-ai/blob/main/types/puter.d.ts"
click node_node_styles "https://github.com/sahrior/cvision-ai/blob/main/app/app.css"
click node_node_public "https://github.com/sahrior/cvision-ai/tree/main/public"
click node_node_build "https://github.com/sahrior/cvision-ai/blob/main/vite.config.ts"

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_node_root,node_node_routes,node_node_navbar toneBlue
class node_node_home,node_node_upload,node_node_resume,node_node_auth,node_node_wipe,node_node_uploader,node_node_report,node_node_summary,node_node_details,node_node_ats,node_node_scores,node_node_accordion toneAmber
class node_node_pdf2img,node_node_puter,node_node_utils,node_node_constants,node_node_types,node_node_puter_types toneMint
class node_node_styles,node_node_public,node_node_build toneRose
```

## Components

### App Shell

React Router SSR application, routes, and shared UI composition.

- [Root shell](https://github.com/sahrior/cvision-ai/blob/main/app/root.tsx): SSR entry · Application-wide shell and providers for the React Router app. · `app/root.tsx`
- [Route map](https://github.com/sahrior/cvision-ai/blob/main/app/routes.ts): router config · Defines the app's route structure and navigation boundaries. · `app/routes.ts`
- [Navbar](https://github.com/sahrior/cvision-ai/blob/main/app/components/Navbar.tsx): layout component · Top-level navigation and shared page chrome. · `app/components/Navbar.tsx`

### Resume Workflow

User-facing resume upload, scoring, report, authentication, and reset flows.

- [Home](https://github.com/sahrior/cvision-ai/blob/main/app/routes/home.tsx): route page · Landing or primary entry route for the app. · `app/routes/home.tsx`
- [Upload](https://github.com/sahrior/cvision-ai/blob/main/app/routes/Upload.tsx): route page · Resume submission and upload orchestration route. · `app/routes/Upload.tsx`
- [Resume report](https://github.com/sahrior/cvision-ai/blob/main/app/routes/resume.tsx): route page · Resume analysis report view and page-level composition. · `app/routes/resume.tsx`
- [Auth](https://github.com/sahrior/cvision-ai/blob/main/app/routes/auth.tsx): route page · Authentication and session establishment flow. · `app/routes/auth.tsx`
- [Wipe](https://github.com/sahrior/cvision-ai/blob/main/app/routes/wipe.tsx): route action · Reset or cleanup flow for stored application data. · `app/routes/wipe.tsx`
- [File uploader](https://github.com/sahrior/cvision-ai/blob/main/app/components/FileUploader.tsx): input component · File selection and submission UI for resume uploads. · `app/components/FileUploader.tsx`
- [Report card](https://github.com/sahrior/cvision-ai/blob/main/app/components/ResumeCard.tsx): display component · Primary resume report container used to present analysis results. · `app/components/ResumeCard.tsx`
- [Summary](https://github.com/sahrior/cvision-ai/blob/main/app/components/Summary.tsx): report component · High-level summary content for the analyzed resume. · `app/components/Summary.tsx`
- [Details](https://github.com/sahrior/cvision-ai/blob/main/app/components/Details.tsx): report component · Expanded detail sections for the resume analysis. · `app/components/Details.tsx`
- [ATS score](https://github.com/sahrior/cvision-ai/blob/main/app/components/ATS.tsx): scoring component · ATS-oriented scoring and evaluation display. · `app/components/ATS.tsx`
- [Score widgets](https://github.com/sahrior/cvision-ai/blob/main/app/components/ScoreBadge.tsx): visualization set · ScoreBadge, ScoreCircle, and ScoreGauge for score presentation. · `app/components/ScoreBadge.tsx`
- [Accordion](https://github.com/sahrior/cvision-ai/blob/main/app/components/Accordion.tsx): ui component · Expandable section control used by report views. · `app/components/Accordion.tsx`

### Shared Logic

Processing, integration, utilities, constants, and shared types.

- [PDF to image](https://github.com/sahrior/cvision-ai/blob/main/app/lib/pdf2img.ts): processing lib · Transforms uploaded PDF resumes into images for preview or analysis. · `app/lib/pdf2img.ts`
- [Puter bridge](https://github.com/sahrior/cvision-ai/blob/main/app/lib/puter.ts): integration lib · External service integration for storage, auth, or backend-like capabilities. · `app/lib/puter.ts`
- [Utilities](https://github.com/sahrior/cvision-ai/blob/main/app/lib/utils.ts): shared helpers · Common helper functions used across routes and components. · `app/lib/utils.ts`
- [Constants](https://github.com/sahrior/cvision-ai/blob/main/constants/index.ts): domain config · Shared domain constants and thresholds. · `constants/index.ts`
- [Types](https://github.com/sahrior/cvision-ai/blob/main/types/index.d.ts): type defs · Shared TypeScript declarations for app and service data shapes. · `types/index.d.ts`
- [Puter types](https://github.com/sahrior/cvision-ai/blob/main/types/puter.d.ts): service types · Type declarations for the Puter integration. · `types/puter.d.ts`

### Runtime & Assets

Build, deployment, and static asset boundaries.

- [App styles](https://github.com/sahrior/cvision-ai/blob/main/app/app.css): stylesheet · Global styling for the application shell and UI. · `app/app.css`
- [Static assets](https://github.com/sahrior/cvision-ai/tree/main/public): assets · Icons and images used by the user interface. · `public`
- [Build setup](https://github.com/sahrior/cvision-ai/blob/main/vite.config.ts): tooling · Vite, React Router config, TypeScript config, and container packaging for SSR deployment. · `vite.config.ts`

## Connections

- Route map → Root shell: mounts · Route structure is composed beneath the root shell.
- Root shell → Navbar: renders · The shell provides shared navigation chrome.
- Route map → Home: includes · Primary app route.
- Route map → Upload: includes · Upload flow route.
- Route map → Resume report: includes · Report route.
- Route map → Auth: includes · Authentication route.
- Route map → Wipe: includes · Reset route.
- Upload → File uploader: uses · Upload page centers on file submission UI.
- Upload → PDF to image: processes · Uploaded PDFs are transformed for downstream use.
- Upload → Puter bridge: persists · Upload flow likely stores or hands off resume data through Puter.
- Resume report → Report card: renders · Report route composes the main result container.
- Resume report → Summary: renders · Shows high-level analysis summary.
- Resume report → Details: renders · Shows expanded analysis details.
- Resume report → ATS score: shows · Displays ATS-style evaluation.
- Resume report → Score widgets: visualizes · Uses score widgets to communicate scoring.
- Resume report → Accordion: expands · Report sections can be expanded or collapsed.
- Auth → Puter bridge: authenticates · Authentication is likely delegated through the external service boundary.
- Wipe → Puter bridge: clears · Reset flow removes stored state or session data.
- Upload → Utilities: shares · Route logic reuses shared helper functions.
- Resume report → Utilities: shares · Report rendering relies on shared helpers.
- Resume report → Constants: uses · Scoring and labels depend on shared constants.
- Upload → Types: types · Upload flow uses shared domain types.
- Resume report → Types: types · Report data is shaped by shared types.
- Puter bridge → Puter types: typed by · Service integration has dedicated declarations.
- Root shell → App styles: loads · Global styles apply at the app shell level.
- Root shell → Static assets: references · UI shell can consume static assets.
- Build setup → Root shell: builds · Tooling compiles the SSR app entry.
- Build setup → Route map: builds · Tooling includes route-based app structure.