# batouldev/ai-job-agent architecture

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

- Interactive diagram: https://gitdiagram.com/batouldev/ai-job-agent
- Repository: https://github.com/batouldev/ai-job-agent

## Overview

This is an AI-assisted job-search application: users sign up, upload and review a CV, set preferences, then receive job matches and manage applications and cover letters from a dashboard. Separate automation workflows ingest jobs and analyze CVs; internal API routes support those workers. The tree also shows payments and a daily-news feature. The graph highlights substantiated calls and data access; several automation-to-API links are dashed because the workflow excerpts do not establish their wiring, and the README offers no product-specific architecture.

Main entry points: [`src/app/api/auth`](https://github.com/batouldev/ai-job-agent/tree/main/src/app/api/auth) (Authentication), [`src/app/dashboard/page.tsx`](https://github.com/batouldev/ai-job-agent/blob/main/src/app/dashboard/page.tsx) (Dashboard and matches), [`src/lib/supabase/server.ts`](https://github.com/batouldev/ai-job-agent/blob/main/src/lib/supabase/server.ts) (Supabase), [`src/lib/ingestion/ingestSourceBatch.ts`](https://github.com/batouldev/ai-job-agent/blob/main/src/lib/ingestion/ingestSourceBatch.ts) (Job ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and onboarding"]
  node_auth["Authentication"]
  node_authlimits["Auth rate limits"]
  node_onboarding["Onboarding"]
end

subgraph group_jobdata["Job discovery"]
  node_ingestion["Job ingestion"]
  node_providers["Job providers<br/>[providerConfig.ts]"]
  node_ingestworkflows["Ingestion workflows"]
  node_matching["Job matching"]
  node_matchworkflow["Matching workflow"]
end

subgraph group_career["Career assistance"]
  node_cvflow["CV analysis"]
  node_cvworker["CV analysis worker"]
  node_coverletters["Cover letters"]
  node_letterworkflow["Letter generation"]
end

subgraph group_app["Job-seeker experience"]
  node_dashboard["Dashboard and matches<br/>[page.tsx]"]
  node_applications["Applications"]
  node_news["Daily job news"]
end

subgraph group_platform["Platform services"]
  node_checkout["Checkout<br/>[route.ts]"]
  node_payments["Payment attempts<br/>[checkout.ts]"]
  node_supabase[("Supabase<br/>[server.ts]")]
  node_adminclient["Admin Supabase client<br/>[admin.ts]"]
end

node_visitor(("Job seeker"))

node_visitor -->|"signs up or in"| node_auth
node_auth -->|"reserves attempts"| node_authlimits
node_auth -->|"authenticates"| node_supabase
node_authlimits -->|"creates client"| node_adminclient
node_auth -->|"routes after sign-in"| node_onboarding
node_visitor -.->|"sets preferences"| node_onboarding
node_onboarding -.->|"submits CV"| node_cvflow
node_cvflow -->|"reads and writes"| node_supabase
node_cvworker -.->|"handles analysis tasks"| node_cvflow
node_ingestworkflows -.->|"runs ingestion"| node_ingestion
node_ingestion -->|"loads provider config"| node_providers
node_ingestion -.->|"upserts jobs"| node_supabase
node_ingestworkflows -.->|"feeds matching"| node_matchworkflow
node_matchworkflow -.->|"runs matching"| node_matching
node_matching -.->|"supplies matches"| node_dashboard
node_visitor -.->|"reviews matches"| node_dashboard
node_dashboard -.->|"manages applications"| node_applications
node_dashboard -.->|"requests letters"| node_coverletters
node_letterworkflow -.->|"generates letters"| node_coverletters
node_visitor -.->|"reads briefings"| node_news
node_visitor -->|"starts checkout"| node_checkout
node_checkout -->|"starts attempt"| node_payments
node_payments -.->|"persists attempt"| node_supabase

click node_auth "https://github.com/batouldev/ai-job-agent/tree/main/src/app/api/auth"
click node_authlimits "https://github.com/batouldev/ai-job-agent/tree/main/src/lib/authRateLimit"
click node_onboarding "https://github.com/batouldev/ai-job-agent/tree/main/src/app/onboarding"
click node_cvflow "https://github.com/batouldev/ai-job-agent/tree/main/src/app/api/cv-analysis"
click node_cvworker "https://github.com/batouldev/ai-job-agent/blob/main/n8n-workflows/cv-analysis-worker.ts"
click node_ingestion "https://github.com/batouldev/ai-job-agent/blob/main/src/lib/ingestion/ingestSourceBatch.ts"
click node_providers "https://github.com/batouldev/ai-job-agent/blob/main/src/lib/ingestion/providerConfig.ts"
click node_ingestworkflows "https://github.com/batouldev/ai-job-agent/blob/main/n8n-workflows/ai-job-agent-01-job-ingestion.ts"
click node_matching "https://github.com/batouldev/ai-job-agent/tree/main/src/lib/matching"
click node_matchworkflow "https://github.com/batouldev/ai-job-agent/blob/main/n8n-workflows/ai-job-agent-02-job-matching.ts"
click node_dashboard "https://github.com/batouldev/ai-job-agent/blob/main/src/app/dashboard/page.tsx"
click node_applications "https://github.com/batouldev/ai-job-agent/tree/main/src/lib/applications"
click node_coverletters "https://github.com/batouldev/ai-job-agent/tree/main/src/lib/coverLetters"
click node_letterworkflow "https://github.com/batouldev/ai-job-agent/blob/main/n8n-workflows/ai-job-agent-03-cover-letter-generation.ts"
click node_news "https://github.com/batouldev/ai-job-agent/tree/main/src/lib/dailyNews"
click node_checkout "https://github.com/batouldev/ai-job-agent/blob/main/src/app/api/checkout/route.ts"
click node_payments "https://github.com/batouldev/ai-job-agent/blob/main/src/lib/payments/checkout.ts"
click node_supabase "https://github.com/batouldev/ai-job-agent/blob/main/src/lib/supabase/server.ts"
click node_adminclient "https://github.com/batouldev/ai-job-agent/blob/main/src/lib/supabase/admin.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_auth,node_authlimits,node_onboarding toneBlue
class node_ingestion,node_providers,node_ingestworkflows,node_matching,node_matchworkflow toneAmber
class node_cvflow,node_cvworker,node_coverletters,node_letterworkflow toneMint
class node_dashboard,node_applications,node_news toneRose
class node_checkout,node_payments,node_supabase,node_adminclient,node_visitor toneIndigo
```

## Components

### Identity and onboarding

- [Authentication](https://github.com/batouldev/ai-job-agent/tree/main/src/app/api/auth): `src/app/api/auth`
- [Auth rate limits](https://github.com/batouldev/ai-job-agent/tree/main/src/lib/authRateLimit): `src/lib/authRateLimit`
- [Onboarding](https://github.com/batouldev/ai-job-agent/tree/main/src/app/onboarding): `src/app/onboarding`

### Job discovery

- [Job ingestion](https://github.com/batouldev/ai-job-agent/blob/main/src/lib/ingestion/ingestSourceBatch.ts): `src/lib/ingestion/ingestSourceBatch.ts`
- [Job providers](https://github.com/batouldev/ai-job-agent/blob/main/src/lib/ingestion/providerConfig.ts): `src/lib/ingestion/providerConfig.ts`
- [Ingestion workflows](https://github.com/batouldev/ai-job-agent/blob/main/n8n-workflows/ai-job-agent-01-job-ingestion.ts): `n8n-workflows/ai-job-agent-01-job-ingestion.ts`
- [Job matching](https://github.com/batouldev/ai-job-agent/tree/main/src/lib/matching): `src/lib/matching`
- [Matching workflow](https://github.com/batouldev/ai-job-agent/blob/main/n8n-workflows/ai-job-agent-02-job-matching.ts): `n8n-workflows/ai-job-agent-02-job-matching.ts`

### Career assistance

- [CV analysis](https://github.com/batouldev/ai-job-agent/tree/main/src/app/api/cv-analysis): `src/app/api/cv-analysis`
- [CV analysis worker](https://github.com/batouldev/ai-job-agent/blob/main/n8n-workflows/cv-analysis-worker.ts): `n8n-workflows/cv-analysis-worker.ts`
- [Cover letters](https://github.com/batouldev/ai-job-agent/tree/main/src/lib/coverLetters): `src/lib/coverLetters`
- [Letter generation](https://github.com/batouldev/ai-job-agent/blob/main/n8n-workflows/ai-job-agent-03-cover-letter-generation.ts): `n8n-workflows/ai-job-agent-03-cover-letter-generation.ts`

### Job-seeker experience

- [Dashboard and matches](https://github.com/batouldev/ai-job-agent/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Applications](https://github.com/batouldev/ai-job-agent/tree/main/src/lib/applications): `src/lib/applications`
- [Daily job news](https://github.com/batouldev/ai-job-agent/tree/main/src/lib/dailyNews): `src/lib/dailyNews`

### Platform services

- [Checkout](https://github.com/batouldev/ai-job-agent/blob/main/src/app/api/checkout/route.ts): `src/app/api/checkout/route.ts`
- [Payment attempts](https://github.com/batouldev/ai-job-agent/blob/main/src/lib/payments/checkout.ts): `src/lib/payments/checkout.ts`
- [Supabase](https://github.com/batouldev/ai-job-agent/blob/main/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- [Admin Supabase client](https://github.com/batouldev/ai-job-agent/blob/main/src/lib/supabase/admin.ts): `src/lib/supabase/admin.ts`

### Other components

- **Job seeker**

## Connections

- Job seeker → Authentication: signs up or in (evidence: `src/app/api/auth/login/route.ts`)
- Authentication → Auth rate limits: reserves attempts (evidence: `src/app/api/auth/login/route.ts`)
- Authentication → Supabase: authenticates (evidence: `src/app/api/auth/login/route.ts`)
- Auth rate limits → Admin Supabase client: creates client (evidence: `src/lib/authRateLimit/rateLimit.ts`)
- Authentication → Onboarding: routes after sign-in
- Job seeker → Onboarding: sets preferences
- Onboarding → CV analysis: submits CV
- CV analysis → Supabase: reads and writes (evidence: `src/app/api/cv-analysis/submit-feedback/route.ts`)
- CV analysis worker → CV analysis: handles analysis tasks
- Ingestion workflows → Job ingestion: runs ingestion
- Job ingestion → Job providers: loads provider config (evidence: `src/lib/ingestion/ingestSourceBatch.ts`)
- Job ingestion → Supabase: upserts jobs
- Ingestion workflows → Matching workflow: feeds matching
- Matching workflow → Job matching: runs matching
- Job matching → Dashboard and matches: supplies matches
- Job seeker → Dashboard and matches: reviews matches
- Dashboard and matches → Applications: manages applications
- Dashboard and matches → Cover letters: requests letters
- Letter generation → Cover letters: generates letters
- Job seeker → Daily job news: reads briefings
- Job seeker → Checkout: starts checkout (evidence: `src/app/api/checkout/route.ts`)
- Checkout → Payment attempts: starts attempt (evidence: `src/app/api/checkout/route.ts`)
- Payment attempts → Supabase: persists attempt