# nishantjaryal/resumestack architecture

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

- Interactive diagram: https://gitdiagram.com/nishantjaryal/resumestack
- Repository: https://github.com/nishantjaryal/resumestack

## Overview

1. **Overall shape**
   - ResumeStack is a **Next.js App Router** full-stack app.
   - It combines **server-rendered pages**, **client-side interactive flows**, **API route handlers**, and a **PostgreSQL + Drizzle** persistence layer.
   - The codebase is organized around domain features rather than a single shared services layer.

2. **Primary user-facing areas**
   - The main application lives under `app/app/...` and includes:
     - **Job info management**: create, edit, view job records.
     - **Resume analysis**: upload/review a resume for a job.
     - **Question generation**: create interview questions and feedback.
     - **Mock interviews**: start and view interview sessions.
     - **Onboarding**, **sign-in/sign-up**, and **upgrade** flows.
   - These routes are the top-level presentation boundary for the product.

3. **Feature-based domain structure**
   - Business logic is split into `features/...` folders:
     - `features/JobInfos`
     - `features/interviews`
     - `features/questions`
     - `features/resumeAnalyses`
     - `features/users`
   - Each feature typically contains:
     - domain-specific DB access
     - permission checks
     - actions/services
     - cache helpers
     - UI-specific components where needed
   - This suggests the app is architected around **bounded contexts** rather than generic controllers.

4. **Data access and persistence**
   - Persistence is managed through **Drizzle ORM** in `drizzle/`.
   - The schema is split by entity:
     - `users`
     - `jobinfo`
     - `questions`
     - `interview`
   - `drizzle/db.ts` is the database entry point, while `drizzle/migrations` holds schema evolution.
   - Feature-level DB modules like `features/*/db.ts` and `dbCache.ts` sit between the UI/actions and the raw schema.

5. **AI capability layer**
   - AI logic is isolated in `services/ai/`.
   - There are separate AI modules for:
     - **questions**
     - **interviews**
     - **resumes**
   - The AI layer uses model/provider abstractions, including `services/ai/models/google.ts` and a Groq integration in `services/ai/groq.ts`.
   - This is the main external intelligence boundary: prompts, schema validation, and provider calls are kept out of the route/page layer.

6. **Server API routes**
   - The app exposes several route handlers under `app/api/...`:
     - `/api/ai/questions/generate-question`
     - `/api/ai/questions/generate-feedback`
     - `/api/ai/resumes/analyze`
     - `/api/webhooks/clerk`
     - `/api/arcjet`
   - These routes likely bridge frontend requests to server-side AI services, auth events, and protection/rate-limit checks.
   - In architecture terms, API routes are the execution boundary for asynchronous or external-triggered operations.

7. **Authentication and user lifecycle**
   - Authentication is handled through **Clerk** via `services/clerk/...`.
   - There are dedicated sign-in/sign-up routes and a Clerk webhook endpoint.
   - `services/clerk/getCurrentUser.ts`, `getPermissions.ts`, and `hasPermissions.ts` indicate server-side identity and authorization checks.
   - The webhook path implies user records or permissions are synchronized into the app’s database after auth events.

8. **Authorization and protection**
   - Permissions are enforced at the feature layer, especially in `features/interviews/permissions.ts`, `features/questions/permissions.ts`, and `features/resumeAnalyses/permissions.ts`.
   - `proxy.ts` and the `app/api/arcjet` route suggest request gating or bot/rate-limit protection is part of the runtime boundary.
   - The architecture separates **identity**, **authorization**, and **request protection** instead of bundling them into page logic.

9. **Interview and conversation support**
   - The interview flow has its own route subtree under `app/app/job-info/[jobInfoID]/interview/...`.
   - Supporting code in `services/hume/...` suggests interview session messaging is processed into condensed chat history for AI use or display.
   - The interview subsystem therefore appears to combine:
     - session UI
     - message collection/condensation
     - AI-driven generation/evaluation
     - persisted interview records

10. **Caching and derived data**
   - Several features include `dbCache.ts` / `dbcache.ts` and `lib/dataCache.ts`.
   - This implies the app caches computed or frequently-read domain data, likely to reduce repeated DB reads and AI recomputation.
   - Derived outputs such as generated questions, resume analysis summaries, and interview feedback are probably treated as cacheable artifacts.

11. **Shared UI and presentation primitives**
   - Reusable UI lives in `components/` and `components/ui/`.
   - The app uses a component library pattern for inputs, dialogs, cards, tables, and other primitives.
   - Shared helpers like `MarkdownRenderer.tsx`, `BackLink.tsx`, and `Skeleton.tsx` support consistent rendering across feature pages.
   - This layer is mostly presentation-only and sits above the domain features.

12. **Environment and deployment concerns**
   - `data/env/client.ts` and `data/env/server.ts` indicate separate client/server environment variable handling.
   - `docker-compose.yml`, `next.config.ts`, and `drizzle` tooling show the app is intended to run with a managed DB and standard Next.js build/deploy flow.
   - The project is production-oriented, with auth, database migrations, webhook handling, and AI provider integration all explicit in the structure.

13. **Suggested diagram boundaries**
   - A clear architecture diagram should show these layers:
     - **Browser/UI routes** in `app/app`
     - **Feature/domain layer** in `features/*`
     - **API handlers** in `app/api/*`
     - **AI provider services** in `services/ai/*`
     - **Auth/identity services** in `services/clerk/*`
     - **Persistence** in `drizzle/*`
     - **Shared utilities/components** in `components/*`, `lib/*`, and `data/env/*`
   - The key data flow is: **user action → route/page → feature action/service → DB and/or AI service → cached/serialized result → UI**.

Main entry points: [`components`](https://github.com/nishantjaryal/resumestack/tree/master/components) (Shared UI), [`app/app/job-info/[jobInfoID]`](https://github.com/nishantjaryal/resumestack/tree/master/app/app/job-info/[jobInfoID]) (Job flows), [`features/interviews`](https://github.com/nishantjaryal/resumestack/tree/master/features/interviews) (Interviews), [`features/questions`](https://github.com/nishantjaryal/resumestack/tree/master/features/questions) (Questions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App routes"]
  node_home["Home<br/>route<br/>[page.tsx]"]
  node_job_routes["Job flows<br/>route subtree"]
  node_onboarding["Onboarding<br/>route<br/>[page.tsx]"]
  node_auth_routes["Auth pages<br/>route<br/>[page.tsx]"]
  node_upgrade["Upgrade<br/>route<br/>[page.tsx]"]
end

subgraph group_api["API routes"]
  node_api_questions["Question API<br/>route handlers"]
  node_api_resumes["Resume API<br/>route handler<br/>[route.ts]"]
  node_api_webhooks["Clerk webhook<br/>route handler<br/>[route.ts]"]
  node_api_arcjet["Arcjet<br/>route handler<br/>[route.ts]"]
end

subgraph group_features["Domain features"]
  node_jobinfos["Job infos<br/>domain feature"]
  node_questions["Questions<br/>domain feature"]
  node_interviews["Interviews<br/>domain feature"]
  node_resume_analyses["Resume analysis<br/>domain feature"]
  node_users["Users<br/>domain feature"]
end

subgraph group_services["Platform services"]
  node_ai_services{{"AI services<br/>provider layer"}}
  node_clerk{{"Clerk auth<br/>identity layer"}}
  node_hume{{"Hume support<br/>conversation utils"}}
end

subgraph group_persistence["Persistence"]
  node_db[("Drizzle DB<br/>database layer<br/>[db.ts]")]
end

subgraph group_shared["Shared layer"]
  node_shared["Shared UI<br/>shared components"]
end

node_home -->|"navigate"| node_job_routes
node_job_routes -->|"loads"| node_jobinfos
node_job_routes -->|"questions"| node_questions
node_job_routes -->|"resume"| node_resume_analyses
node_job_routes -->|"interviews"| node_interviews
node_onboarding -->|"profile"| node_users
node_auth_routes -->|"sign in"| node_clerk
node_upgrade -->|"subscription"| node_clerk
node_api_questions -->|"generate"| node_ai_services
node_api_resumes -->|"analyze"| node_ai_services
node_api_webhooks -->|"sync"| node_clerk
node_api_arcjet -->|"protect"| node_shared
node_questions -->|"persist"| node_db
node_interviews -->|"persist"| node_db
node_jobinfos -->|"persist"| node_db
node_users -->|"persist"| node_db
node_questions -->|"prompt"| node_ai_services
node_interviews -->|"evaluate"| node_ai_services
node_resume_analyses -->|"analyze"| node_ai_services
node_interviews -->|"chat history"| node_hume
node_jobinfos -->|"ui"| node_shared
node_questions -->|"ui"| node_shared
node_interviews -->|"ui"| node_shared
node_resume_analyses -->|"ui"| node_shared
node_clerk -->|"identity"| node_users
node_clerk -->|"ui"| node_shared
node_api_questions -->|"domain"| node_questions
node_api_resumes -->|"domain"| node_resume_analyses
node_api_webhooks -->|"domain"| node_users

click node_home "https://github.com/nishantjaryal/resumestack/blob/master/app/page.tsx"
click node_job_routes "https://github.com/nishantjaryal/resumestack/tree/master/app/app/job-info/[jobInfoID]"
click node_onboarding "https://github.com/nishantjaryal/resumestack/blob/master/app/onboarding/page.tsx"
click node_auth_routes "https://github.com/nishantjaryal/resumestack/blob/master/app/sign-in/[[...sign-in]]/page.tsx"
click node_upgrade "https://github.com/nishantjaryal/resumestack/blob/master/app/app/upgrade/page.tsx"
click node_api_questions "https://github.com/nishantjaryal/resumestack/tree/master/app/api/ai/questions"
click node_api_resumes "https://github.com/nishantjaryal/resumestack/blob/master/app/api/ai/resumes/analyze/route.ts"
click node_api_webhooks "https://github.com/nishantjaryal/resumestack/blob/master/app/api/webhooks/clerk/route.ts"
click node_api_arcjet "https://github.com/nishantjaryal/resumestack/blob/master/app/api/arcjet/route.ts"
click node_jobinfos "https://github.com/nishantjaryal/resumestack/tree/master/features/JobInfos"
click node_questions "https://github.com/nishantjaryal/resumestack/tree/master/features/questions"
click node_interviews "https://github.com/nishantjaryal/resumestack/tree/master/features/interviews"
click node_resume_analyses "https://github.com/nishantjaryal/resumestack/tree/master/features/resumeAnalyses"
click node_users "https://github.com/nishantjaryal/resumestack/tree/master/features/users"
click node_ai_services "https://github.com/nishantjaryal/resumestack/tree/master/services/ai"
click node_clerk "https://github.com/nishantjaryal/resumestack/tree/master/services/clerk"
click node_hume "https://github.com/nishantjaryal/resumestack/tree/master/services/hume"
click node_db "https://github.com/nishantjaryal/resumestack/blob/master/drizzle/db.ts"
click node_shared "https://github.com/nishantjaryal/resumestack/tree/master/components"

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_home,node_job_routes,node_onboarding,node_auth_routes,node_upgrade toneBlue
class node_api_questions,node_api_resumes,node_api_webhooks,node_api_arcjet toneAmber
class node_jobinfos,node_questions,node_interviews,node_resume_analyses,node_users toneMint
class node_ai_services,node_clerk,node_hume toneRose
class node_db toneIndigo
class node_shared toneTeal
```

## Components

### App routes

Next.js App Router pages and interactive route subtrees.

- [Home](https://github.com/nishantjaryal/resumestack/blob/master/app/page.tsx): route · Top-level landing and entry routes. · `app/page.tsx`
- [Job flows](https://github.com/nishantjaryal/resumestack/tree/master/app/app/job-info/[jobInfoID]): route subtree · Job info creation, editing, viewing, resume, questions, and interviews. · `app/app/job-info/[jobInfoID]`
- [Onboarding](https://github.com/nishantjaryal/resumestack/blob/master/app/onboarding/page.tsx): route · User onboarding flow. · `app/onboarding/page.tsx`
- [Auth pages](https://github.com/nishantjaryal/resumestack/blob/master/app/sign-in/[[...sign-in]]/page.tsx): route · Sign-in and sign-up pages. · `app/sign-in/[[...sign-in]]/page.tsx`
- [Upgrade](https://github.com/nishantjaryal/resumestack/blob/master/app/app/upgrade/page.tsx): route · Upgrade or pricing flow. · `app/app/upgrade/page.tsx`

### API routes

Route handlers for AI, webhooks, and protection.

- [Question API](https://github.com/nishantjaryal/resumestack/tree/master/app/api/ai/questions): route handlers · Generate questions and feedback endpoints. · `app/api/ai/questions`
- [Resume API](https://github.com/nishantjaryal/resumestack/blob/master/app/api/ai/resumes/analyze/route.ts): route handler · Resume analysis endpoint. · `app/api/ai/resumes/analyze/route.ts`
- [Clerk webhook](https://github.com/nishantjaryal/resumestack/blob/master/app/api/webhooks/clerk/route.ts): route handler · Auth lifecycle sync from Clerk. · `app/api/webhooks/clerk/route.ts`
- [Arcjet](https://github.com/nishantjaryal/resumestack/blob/master/app/api/arcjet/route.ts): route handler · Request protection and gating endpoint. · `app/api/arcjet/route.ts`

### Domain features

Feature-bounded business logic and domain services.

- [Job infos](https://github.com/nishantjaryal/resumestack/tree/master/features/JobInfos): domain feature · Job record state, permissions, cache, and actions. · `features/JobInfos`
- [Questions](https://github.com/nishantjaryal/resumestack/tree/master/features/questions): domain feature · Interview question generation, formatting, permissions, and cache. · `features/questions`
- [Interviews](https://github.com/nishantjaryal/resumestack/tree/master/features/interviews): domain feature · Interview sessions, actions, permissions, and derived state. · `features/interviews`
- [Resume analysis](https://github.com/nishantjaryal/resumestack/tree/master/features/resumeAnalyses): domain feature · Resume analysis permissions and feature boundary. · `features/resumeAnalyses`
- [Users](https://github.com/nishantjaryal/resumestack/tree/master/features/users): domain feature · User sync, actions, cache, and DB access. · `features/users`

### Platform services

External integrations and cross-cutting backend services.

- [AI services](https://github.com/nishantjaryal/resumestack/tree/master/services/ai): provider layer · Prompted AI workflows for questions, interviews, and resumes. · `services/ai`
- [Clerk auth](https://github.com/nishantjaryal/resumestack/tree/master/services/clerk): identity layer · Current user, permissions, and auth UI components. · `services/clerk`
- [Hume support](https://github.com/nishantjaryal/resumestack/tree/master/services/hume): conversation utils · Chat message collection and condensation for interview support. · `services/hume`

### Persistence

Drizzle schema and database entrypoints.

- [Drizzle DB](https://github.com/nishantjaryal/resumestack/blob/master/drizzle/db.ts): database layer · Database entrypoint, schema, and migrations. · `drizzle/db.ts`

### Shared layer

Reusable UI, utilities, and environment helpers.

- [Shared UI](https://github.com/nishantjaryal/resumestack/tree/master/components): shared components · Reusable UI components, utilities, and env helpers. · `components`

## Connections

- Home → Job flows: navigate · Primary product entry leads into job-centric workflows.
- Job flows → Job infos: loads · Routes read and mutate job info domain data.
- Job flows → Questions: questions · Question pages depend on generated and persisted interview questions.
- Job flows → Resume analysis: resume · Resume review routes invoke analysis features.
- Job flows → Interviews: interviews · Interview routes orchestrate session creation and viewing.
- Onboarding → Users: profile · Onboarding likely initializes or updates user records.
- Auth pages → Clerk auth: sign in · Auth pages are backed by Clerk components and session state.
- Upgrade → Clerk auth: subscription · Upgrade flow is tied to authenticated user identity.
- Question API → AI services: generate · Question endpoints delegate to AI generation services.
- Resume API → AI services: analyze · Resume analysis endpoint calls the AI resume pipeline.
- Clerk webhook → Clerk auth: sync · Webhook receives Clerk events and aligns app users.
- Arcjet → Shared UI: protect · Protection boundary may use shared request helpers and config.
- Questions → Drizzle DB: persist · Questions feature stores and reads domain records.
- Interviews → Drizzle DB: persist · Interviews feature stores and reads session data.
- Job infos → Drizzle DB: persist · Job info feature stores job records and derived cache entries.
- Users → Drizzle DB: persist · Users feature reads and writes user metadata.
- Questions → AI services: prompt · Domain logic prepares AI prompts and parses structured output.
- Interviews → AI services: evaluate · Interview flows use AI for generation and feedback.
- Resume analysis → AI services: analyze · Resume analysis feature sits on top of AI resume services.
- Interviews → Hume support: chat history · Interview support condenses and fetches conversation messages.
- Job infos → Shared UI: ui · Feature components reuse shared UI primitives and helpers.
- Questions → Shared UI: ui · Question views use shared rendering and component primitives.
- Interviews → Shared UI: ui · Interview pages and components share common UI building blocks.
- Resume analysis → Shared UI: ui · Resume flow uses shared components and env helpers.
- Clerk auth → Users: identity · Auth services support user lookup, permissions, and lifecycle sync.
- Clerk auth → Shared UI: ui · Clerk components integrate with the shared presentation layer.
- Question API → Questions: domain · API routes bridge the HTTP boundary into question domain logic.
- Resume API → Resume analysis: domain · API routes bridge the HTTP boundary into resume analysis logic.
- Clerk webhook → Users: domain · Webhook updates the user feature after auth events.
