# 27aran/jobby architecture

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

- Interactive diagram: https://gitdiagram.com/27aran/jobby
- Repository: https://github.com/27aran/jobby

## Overview

Jobby is an AI job-search assistant with two evidenced runtime strands: collecting job listings into SQLite, and preparing profile documents for vector search and job-profile matching. The README also advertises grounded cover-letter generation, but the supplied tree and excerpts do not show its implementation, so it is represented only as a documented capability. The RAG indexing path is shown in the store module’s executable block; no inspected source connects retrieval to job search or cover-letter generation.

Main entry points: [`src/jobby/rag/store.py`](https://github.com/27aran/jobby/blob/main/src/jobby/rag/store.py) (Qdrant index), [`src/jobby/rag/retrieval.py`](https://github.com/27aran/jobby/blob/main/src/jobby/rag/retrieval.py) (Profile retrieval), [`src/jobby/models.py`](https://github.com/27aran/jobby/blob/main/src/jobby/models.py) (Job and profile records), [`src/jobby/sources/cli.py`](https://github.com/27aran/jobby/blob/main/src/jobby/sources/cli.py) (Fetch-new-jobs flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_jobs["Job collection"]
  node_source_cli["Fetch-new-jobs flow<br/>[cli.py]"]
  node_job_search["Listing search and details<br/>[arbeitsagentur.py]"]
  node_job_db[("Jobs SQLite store<br/>[db.py]")]
  node_job_api{{"Arbeitsagentur API"}}
end

subgraph group_rag["Profile RAG"]
  node_doc_load["Profile document loader<br/>[ingest.py]"]
  node_chunking["Profile chunking<br/>[chunk.py]"]
  node_embedding["Text embeddings<br/>[embed.py]"]
  node_vector_store[("Qdrant index<br/>[store.py]")]
end

subgraph group_core["Shared domain"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_models["Job and profile records<br/>[models.py]"]
end

subgraph group_outputs["Matching and applications"]
  node_retrieval["Profile retrieval<br/>[retrieval.py]"]
  node_matching["Job-profile matching"]
  node_cover_letter["Grounded cover letters"]
end

node_user(("Job seeker"))

node_user -->|"starts collection"| node_source_cli
node_source_cli -->|"searches and fetches"| node_job_search
node_job_search -->|"requests listings"| node_job_api
node_source_cli -->|"checks and saves"| node_job_db
node_job_db -->|"reads database path"| node_settings
node_job_search -->|"creates jobs"| node_models
node_doc_load -->|"creates documents"| node_models
node_chunking -->|"creates chunks"| node_models
node_chunking -->|"loads documents in script"| node_doc_load
node_vector_store -->|"loads documents in script"| node_doc_load
node_vector_store -->|"chunks documents in script"| node_chunking
node_vector_store -->|"embeds chunks"| node_embedding
node_embedding -->|"reads model setting"| node_settings
node_vector_store -->|"reads index path"| node_settings
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"queries index"| node_vector_store
node_retrieval -->|"returns profile matches"| node_models
node_user -.->|"searches profile"| node_retrieval
node_retrieval -.->|"supports matching"| node_matching
node_matching -.->|"grounds generation"| node_cover_letter
node_user -.->|"requests application help"| node_cover_letter

click node_source_cli "https://github.com/27aran/jobby/blob/main/src/jobby/sources/cli.py"
click node_job_search "https://github.com/27aran/jobby/blob/main/src/jobby/sources/arbeitsagentur.py"
click node_job_db "https://github.com/27aran/jobby/blob/main/src/jobby/storage/db.py"
click node_settings "https://github.com/27aran/jobby/blob/main/src/jobby/config.py"
click node_models "https://github.com/27aran/jobby/blob/main/src/jobby/models.py"
click node_doc_load "https://github.com/27aran/jobby/blob/main/src/jobby/rag/ingest.py"
click node_chunking "https://github.com/27aran/jobby/blob/main/src/jobby/rag/chunk.py"
click node_embedding "https://github.com/27aran/jobby/blob/main/src/jobby/rag/embed.py"
click node_vector_store "https://github.com/27aran/jobby/blob/main/src/jobby/rag/store.py"
click node_retrieval "https://github.com/27aran/jobby/blob/main/src/jobby/rag/retrieval.py"
click node_matching "https://github.com/27aran/jobby/tree/main/src/jobby"
click node_cover_letter "https://github.com/27aran/jobby/tree/main/src/jobby"

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_source_cli,node_job_search,node_job_db,node_job_api toneBlue
class node_doc_load,node_chunking,node_embedding,node_vector_store toneAmber
class node_settings,node_models toneMint
class node_retrieval,node_matching,node_cover_letter toneRose
class node_user toneIndigo
```

## Components

### Job collection

- [Fetch-new-jobs flow](https://github.com/27aran/jobby/blob/main/src/jobby/sources/cli.py): `src/jobby/sources/cli.py`
- [Listing search and details](https://github.com/27aran/jobby/blob/main/src/jobby/sources/arbeitsagentur.py): `src/jobby/sources/arbeitsagentur.py`
- [Jobs SQLite store](https://github.com/27aran/jobby/blob/main/src/jobby/storage/db.py): `src/jobby/storage/db.py`
- **Arbeitsagentur API**

### Profile RAG

- [Profile document loader](https://github.com/27aran/jobby/blob/main/src/jobby/rag/ingest.py): `src/jobby/rag/ingest.py`
- [Profile chunking](https://github.com/27aran/jobby/blob/main/src/jobby/rag/chunk.py): `src/jobby/rag/chunk.py`
- [Text embeddings](https://github.com/27aran/jobby/blob/main/src/jobby/rag/embed.py): `src/jobby/rag/embed.py`
- [Qdrant index](https://github.com/27aran/jobby/blob/main/src/jobby/rag/store.py): `src/jobby/rag/store.py`

### Shared domain

- [Runtime settings](https://github.com/27aran/jobby/blob/main/src/jobby/config.py): `src/jobby/config.py`
- [Job and profile records](https://github.com/27aran/jobby/blob/main/src/jobby/models.py): `src/jobby/models.py`

### Matching and applications

- [Profile retrieval](https://github.com/27aran/jobby/blob/main/src/jobby/rag/retrieval.py): `src/jobby/rag/retrieval.py`
- [Job-profile matching](https://github.com/27aran/jobby/tree/main/src/jobby): `src/jobby`
- [Grounded cover letters](https://github.com/27aran/jobby/tree/main/src/jobby): `src/jobby`

### Other components

- **Job seeker**

## Connections

- Job seeker → Fetch-new-jobs flow: starts collection (evidence: `src/jobby/sources/cli.py`)
- Fetch-new-jobs flow → Listing search and details: searches and fetches (evidence: `src/jobby/sources/cli.py`)
- Listing search and details → Arbeitsagentur API: requests listings (evidence: `src/jobby/sources/arbeitsagentur.py`)
- Fetch-new-jobs flow → Jobs SQLite store: checks and saves (evidence: `src/jobby/sources/cli.py`)
- Jobs SQLite store → Runtime settings: reads database path (evidence: `src/jobby/storage/db.py`)
- Listing search and details → Job and profile records: creates jobs (evidence: `src/jobby/sources/arbeitsagentur.py`)
- Profile document loader → Job and profile records: creates documents (evidence: `src/jobby/rag/ingest.py`)
- Profile chunking → Job and profile records: creates chunks (evidence: `src/jobby/rag/chunk.py`)
- Profile chunking → Profile document loader: loads documents in script (evidence: `src/jobby/rag/chunk.py`)
- Qdrant index → Profile document loader: loads documents in script (evidence: `src/jobby/rag/store.py`)
- Qdrant index → Profile chunking: chunks documents in script (evidence: `src/jobby/rag/store.py`)
- Qdrant index → Text embeddings: embeds chunks (evidence: `src/jobby/rag/store.py`)
- Text embeddings → Runtime settings: reads model setting (evidence: `src/jobby/rag/embed.py`)
- Qdrant index → Runtime settings: reads index path (evidence: `src/jobby/rag/store.py`)
- Profile retrieval → Text embeddings: embeds query (evidence: `src/jobby/rag/retrieval.py`)
- Profile retrieval → Qdrant index: queries index (evidence: `src/jobby/rag/retrieval.py`)
- Profile retrieval → Job and profile records: returns profile matches (evidence: `src/jobby/rag/retrieval.py`)
- Job seeker → Profile retrieval: searches profile
- Profile retrieval → Job-profile matching: supports matching (evidence: `README.md`)
- Job-profile matching → Grounded cover letters: grounds generation (evidence: `README.md`)
- Job seeker → Grounded cover letters: requests application help (evidence: `README.md`)
