# blu59204/careercraftsai architecture

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

- Interactive diagram: https://gitdiagram.com/blu59204/careercraftsai
- Repository: https://github.com/blu59204/careercraftsai

## Overview

CareerCraft AI is a self-hosted, full-stack job-search automation platform. Users work in the Next.js app, which calls the FastAPI API over REST and SSE; agent runs and job searches progress through durable Temporal workflows. Specialized agents cover role discovery, resume and application materials, company and salary research, outreach, and interview preparation. Applications pass through form filling and explicit human-approval checkpoints before submission. The README documents additional capabilities not represented in sampled implementation excerpts; those are shown at their documented subsystem paths, without asserting unverified internal wiring.

Main entry points: [`backend/app/agents/auto_apply_pipeline.py`](https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/auto_apply_pipeline.py) (Application pipeline), [`backend/app/api/v1/agents.py`](https://github.com/blu59204/careercraftsai/blob/master/backend/app/api/v1/agents.py) (Agent endpoints), [`backend/app/agents/harness.py`](https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/harness.py) (Agent harness), [`backend/app/agents/orchestrator.py`](https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/orchestrator.py) (Agent supervisor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["User product"]
  node_frontend["CareerCraft app"]
  node_extension["Browser extension<br/>[background.js]"]
  node_approval["Human approval<br/>[ApprovalModal.tsx]"]
end

subgraph group_api["API and agents"]
  node_api["FastAPI API<br/>[main.py]"]
  node_agent_routes["Agent endpoints<br/>[agents.py]"]
  node_harness["Agent harness<br/>[harness.py]"]
  node_orchestrator["Agent supervisor<br/>[orchestrator.py]"]
  node_job_search["Job discovery<br/>[job_search.py]"]
  node_resume["Resume tailoring<br/>[resume_agent.py]"]
  node_autoapply["Application pipeline"]
  node_other_agents["Career agents"]
  node_application_service["Application workflow"]
  node_extension_api["Extension endpoints<br/>[extension.py]"]
  node_formfill["Form filling"]
  node_model_router["BYOK model routing<br/>[model_router.py]"]
end

subgraph group_workflow["Durable workflows"]
  node_temporal["Temporal workflows"]
end

subgraph group_data["Data and memory"]
  node_rag["Document RAG<br/>[rag_service.py]"]
  node_postgres[("PostgreSQL and pgvector<br/>[database.py]")]
  node_redis[("Redis sessions and events<br/>[redis_client.py]")]
  node_storage["Document storage<br/>[storage_service.py]"]
  node_memory["Agent memory<br/>[manager.py]"]
end

subgraph group_integrations["External integrations"]
  node_ai_providers["AI providers"]
  node_integrations["Connected services"]
  node_decision["Decision engine<br/>[decision_engine.py]"]
  node_decision_service["Jev or Laya"]
end

node_user(("Job seeker"))

node_user -->|"uses"| node_frontend
node_frontend -->|"REST and SSE"| node_api
node_user -->|"pairs browser"| node_extension
node_api -->|"routes requests"| node_agent_routes
node_agent_routes -->|"runs agents"| node_harness
node_harness -->|"routes tasks"| node_orchestrator
node_orchestrator -->|"dispatches search"| node_job_search
node_orchestrator -->|"dispatches tailoring"| node_resume
node_orchestrator -->|"dispatches tasks"| node_other_agents
node_agent_routes -->|"starts workflows"| node_temporal
node_temporal -->|"runs searches"| node_job_search
node_temporal -->|"runs applications"| node_autoapply
node_autoapply -->|"finds roles"| node_job_search
node_autoapply -->|"tailors resume"| node_resume
node_autoapply -->|"loads resume"| node_application_service
node_autoapply -->|"requests review"| node_approval
node_approval -->|"shows checkpoint"| node_frontend
node_temporal -->|"queues extension tasks"| node_extension_api
node_extension -->|"claims tasks"| node_extension_api
node_extension_api -->|"dispatches filling"| node_formfill
node_formfill -->|"presents application"| node_approval
node_agent_routes -->|"serves RAG"| node_rag
node_rag -->|"stores vectors"| node_postgres
node_rag -->|"stores documents"| node_storage
node_harness -->|"uses context"| node_memory
node_memory -->|"persists memory"| node_postgres
node_memory -->|"stores sessions"| node_redis
node_harness -->|"requests completions"| node_model_router
node_model_router -->|"routes models"| node_ai_providers
node_api -.->|"uses connectors"| node_integrations
node_formfill -.->|"resolves decisions"| node_decision
node_decision -.->|"queries engine"| node_decision_service

click node_frontend "https://github.com/blu59204/careercraftsai/tree/master/frontend/src/app/(app)"
click node_extension "https://github.com/blu59204/careercraftsai/blob/master/extension/src/background.js"
click node_api "https://github.com/blu59204/careercraftsai/blob/master/backend/app/main.py"
click node_agent_routes "https://github.com/blu59204/careercraftsai/blob/master/backend/app/api/v1/agents.py"
click node_harness "https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/harness.py"
click node_orchestrator "https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/orchestrator.py"
click node_job_search "https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/job_search.py"
click node_resume "https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/resume_agent.py"
click node_autoapply "https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/auto_apply_pipeline.py"
click node_other_agents "https://github.com/blu59204/careercraftsai/tree/master/backend/app/agents"
click node_application_service "https://github.com/blu59204/careercraftsai/blob/master/backend/app/services/application_workflow.py"
click node_temporal "https://github.com/blu59204/careercraftsai/tree/master/backend/app/workflows"
click node_extension_api "https://github.com/blu59204/careercraftsai/blob/master/backend/app/api/v1/extension.py"
click node_formfill "https://github.com/blu59204/careercraftsai/blob/master/backend/app/services/form_filler_service.py"
click node_approval "https://github.com/blu59204/careercraftsai/blob/master/frontend/src/components/agents/ApprovalModal.tsx"
click node_rag "https://github.com/blu59204/careercraftsai/blob/master/backend/app/services/rag_service.py"
click node_postgres "https://github.com/blu59204/careercraftsai/blob/master/backend/app/core/database.py"
click node_redis "https://github.com/blu59204/careercraftsai/blob/master/backend/app/core/redis_client.py"
click node_storage "https://github.com/blu59204/careercraftsai/blob/master/backend/app/services/storage_service.py"
click node_memory "https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/memory/manager.py"
click node_model_router "https://github.com/blu59204/careercraftsai/blob/master/backend/app/core/model_router.py"
click node_integrations "https://github.com/blu59204/careercraftsai/tree/master/backend/app/integrations"
click node_decision "https://github.com/blu59204/careercraftsai/blob/master/backend/app/services/decision_engine.py"

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_frontend,node_extension,node_approval toneBlue
class node_api,node_agent_routes,node_harness,node_orchestrator,node_job_search,node_resume,node_autoapply,node_other_agents,node_application_service,node_extension_api,node_formfill,node_model_router toneAmber
class node_temporal toneMint
class node_rag,node_postgres,node_redis,node_storage,node_memory toneRose
class node_ai_providers,node_integrations,node_decision,node_decision_service,node_user toneIndigo
```

## Components

### User product

- [CareerCraft app](https://github.com/blu59204/careercraftsai/tree/master/frontend/src/app/(app)): `frontend/src/app/(app)`
- [Browser extension](https://github.com/blu59204/careercraftsai/blob/master/extension/src/background.js): `extension/src/background.js`
- [Human approval](https://github.com/blu59204/careercraftsai/blob/master/frontend/src/components/agents/ApprovalModal.tsx): `frontend/src/components/agents/ApprovalModal.tsx`

### API and agents

- [FastAPI API](https://github.com/blu59204/careercraftsai/blob/master/backend/app/main.py): `backend/app/main.py`
- [Agent endpoints](https://github.com/blu59204/careercraftsai/blob/master/backend/app/api/v1/agents.py): `backend/app/api/v1/agents.py`
- [Agent harness](https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/harness.py): `backend/app/agents/harness.py`
- [Agent supervisor](https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/orchestrator.py): `backend/app/agents/orchestrator.py`
- [Job discovery](https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/job_search.py): `backend/app/agents/job_search.py`
- [Resume tailoring](https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/resume_agent.py): `backend/app/agents/resume_agent.py`
- [Application pipeline](https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/auto_apply_pipeline.py): `backend/app/agents/auto_apply_pipeline.py`
- [Career agents](https://github.com/blu59204/careercraftsai/tree/master/backend/app/agents): `backend/app/agents`
- [Application workflow](https://github.com/blu59204/careercraftsai/blob/master/backend/app/services/application_workflow.py): `backend/app/services/application_workflow.py`
- [Extension endpoints](https://github.com/blu59204/careercraftsai/blob/master/backend/app/api/v1/extension.py): `backend/app/api/v1/extension.py`
- [Form filling](https://github.com/blu59204/careercraftsai/blob/master/backend/app/services/form_filler_service.py): `backend/app/services/form_filler_service.py`
- [BYOK model routing](https://github.com/blu59204/careercraftsai/blob/master/backend/app/core/model_router.py): `backend/app/core/model_router.py`

### Durable workflows

- [Temporal workflows](https://github.com/blu59204/careercraftsai/tree/master/backend/app/workflows): `backend/app/workflows`

### Data and memory

- [Document RAG](https://github.com/blu59204/careercraftsai/blob/master/backend/app/services/rag_service.py): `backend/app/services/rag_service.py`
- [PostgreSQL and pgvector](https://github.com/blu59204/careercraftsai/blob/master/backend/app/core/database.py): `backend/app/core/database.py`
- [Redis sessions and events](https://github.com/blu59204/careercraftsai/blob/master/backend/app/core/redis_client.py): `backend/app/core/redis_client.py`
- [Document storage](https://github.com/blu59204/careercraftsai/blob/master/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`
- [Agent memory](https://github.com/blu59204/careercraftsai/blob/master/backend/app/agents/memory/manager.py): `backend/app/agents/memory/manager.py`

### External integrations

- **AI providers**
- [Connected services](https://github.com/blu59204/careercraftsai/tree/master/backend/app/integrations): `backend/app/integrations`
- [Decision engine](https://github.com/blu59204/careercraftsai/blob/master/backend/app/services/decision_engine.py): `backend/app/services/decision_engine.py`
- **Jev or Laya**

### Other components

- **Job seeker**

## Connections

- Job seeker → CareerCraft app: uses
- CareerCraft app → FastAPI API: REST and SSE
- Job seeker → Browser extension: pairs browser
- FastAPI API → Agent endpoints: routes requests
- Agent endpoints → Agent harness: runs agents
- Agent harness → Agent supervisor: routes tasks
- Agent supervisor → Job discovery: dispatches search
- Agent supervisor → Resume tailoring: dispatches tailoring
- Agent supervisor → Career agents: dispatches tasks
- Agent endpoints → Temporal workflows: starts workflows
- Temporal workflows → Job discovery: runs searches
- Temporal workflows → Application pipeline: runs applications
- Application pipeline → Job discovery: finds roles
- Application pipeline → Resume tailoring: tailors resume
- Application pipeline → Application workflow: loads resume
- Application pipeline → Human approval: requests review
- Human approval → CareerCraft app: shows checkpoint
- Temporal workflows → Extension endpoints: queues extension tasks
- Browser extension → Extension endpoints: claims tasks
- Extension endpoints → Form filling: dispatches filling
- Form filling → Human approval: presents application
- Agent endpoints → Document RAG: serves RAG
- Document RAG → PostgreSQL and pgvector: stores vectors
- Document RAG → Document storage: stores documents
- Agent harness → Agent memory: uses context
- Agent memory → PostgreSQL and pgvector: persists memory
- Agent memory → Redis sessions and events: stores sessions
- Agent harness → BYOK model routing: requests completions
- BYOK model routing → AI providers: routes models
- FastAPI API → Connected services: uses connectors
- Form filling → Decision engine: resolves decisions
- Decision engine → Jev or Laya: queries engine