# AI-Job-Search Codebase Structure: Understanding the Repository Layout

> Explore the ai-job-search codebase structure. Understand the repository layout featuring a thin-pointer architecture for reproducible AI application pipelines using Claude Code.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: internals
- Published: 2026-09-02

---

**The ai-job-search repository separates core AI workflows, job portal integrations, and user assets into a thin-pointer architecture that enables reproducible application pipelines via Claude Code commands.**

The MadsLorentzen/ai-job-search repository implements a structured framework for AI-assisted job searching. Understanding the ai-job-search codebase structure reveals a deliberate separation between workflow definitions in `.claude/`, external tool integrations in `.agents/`, and personal document assets. This design allows users to maintain sensitive candidate data in private forks while leveraging shared automation logic and LaTeX templates.

## Core Workflow Definitions (`.claude/`)

The `.claude/` directory contains the central nervous system of the application, defining how Claude Code agents execute job search workflows.

### Skill Definitions and Workflow Rules

The primary skill definition resides in [`.claude/skills/job-application-assistant/SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-application-assistant/SKILL.md). This file declares the *job-application-assistant* skill, describing its allowed tools and the step-by-step workflow covering research, CV tailoring, cover-letter drafting, and interview preparation. The skill references seven supporting files that define specific evaluation criteria and persona configurations.

During the onboarding process, the `/setup` command defined in [`.claude/commands/setup.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/commands/setup.md) reads source materials from the `documents/` folder and populates these skill files, ultimately generating the master [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) candidate profile.

### Command Specifications

Each slash command available to users exists as a Markdown file under `.claude/commands/`:

- [`setup.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/setup.md) - Implements the onboarding wizard with Path A, B, and C workflows
- [`apply.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/apply.md) - Orchestrates the full application pipeline from parsing to PDF compilation  
- [`rank.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/rank.md) - Provides job ranking functionality

These files contain exact procedural steps the agent must follow when invoked, effectively serving as executable documentation.

### Permission Manifest

The [`.claude/settings.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/settings.json) file lists tools the Claude Code runtime may invoke, including `Read`, `Glob`, `WebFetch`, and others. This enforces the thin-pointer security model by explicitly declaring permissible system interactions.

## Portal-Specific Search Tools (`.agents/skills/`)

The `.agents/skills/` directory houses self-contained CLI integrations for individual job boards. Each portal skill follows a common contract implementing `search` and `detail` commands, an `enabled:` flag in its [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md), and support for JSON, table, or plain text output.

The repository includes integrations for:

- **Jobbank** (Denmark) - `.agents/skills/jobbank-search` for public-sector positions
- **Jobdanmark** (Denmark) - `.agents/skills/jobdanmark-search` for national employment services  
- **Jobindex** (Denmark) - `.agents/skills/jobindex-search` for private aggregator listings
- **Jobnet** (Denmark) - `.agents/skills/jobnet-search` for government portals
- **LinkedIn** (Global) - `.agents/skills/linkedin-search` using guest-mode API with zero dependencies
- **freehire** (Global) - `.agents/skills/freehire-search` for tech-focused REST API aggregation

The `/scrape` command auto-discovers any enabled skills in this directory, executing searches across all active portals and deduplicating results based on the scoring framework defined in [`04-job-evaluation.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/04-job-evaluation.md).

## User-Facing Document Assets

### LaTeX Templates

The `cv/` and `cover_letters/` directories contain professional typesetting templates. The `cv/main_example.tex` file provides a moderncv-based curriculum vitae template, while `cover_letters/cover.cls` defines a custom LaTeX class for cover letters with accompanying example documents. The `/apply` command renders these templates using candidate-specific data extracted during setup.

### Source Material Archive

The `documents/` folder serves as the user-facing intake for raw materials. As specified in [`documents/README.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/documents/README.md), this directory holds CV PDFs, LinkedIn data exports, diplomas, reference letters, and archives of past applications. The `/setup` command validates and indexes these files to populate the AI workflow memory.

## Utility Tools and Testing Infrastructure

The `tools/` directory contains helper scripts supporting the automation pipeline. The [`tools/verify_pdf.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/verify_pdf.py) script performs ATS compatibility checks by verifying PDF layout and extractable text. Additional utilities include [`check_upstream_updates.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/check_upstream_updates.py) for safe repository synchronization.

The `tests/` directory maintains pytest suites verifying correctness for every command and tool, including integration tests like [`test_apply_records_application.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/test_apply_records_application.py) that validate the end-to-end application recording workflow.

## Runtime State and Persistence

The repository maintains operational state in two key locations:

- `job_scraper/` - Stores transient scraper cache including [`seen_jobs.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/seen_jobs.json) and temporary search results
- `job_search_tracker.csv` - Persistent CSV dashboard summarizing all applications, outcomes, and pipeline status

These files enable the system to maintain continuity across sessions while keeping sensitive tracking data under user control.

## Executing Core Workflows

The ai-job-search codebase structure supports several key operational commands. To initialize the system, users run the onboarding flow:

```bash
claude          # start Claude Code REPL

/setup          # invoke the /setup command – chooses Path A, B, or C automatically

```

This populates the skill files and generates [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) from the `documents/` folder.

To search across all enabled job portals:

```bash
/scrape

```

This discovers enabled skills in `.agents/skills/`, executes searches, and presents ranked results.

To apply to a specific posting:

```bash
/apply https://jobindex.dk/job/1234567

```

This executes the full pipeline: parsing the posting, evaluating fit, drafting LaTeX documents, running ATS verification via [`verify_pdf.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/verify_pdf.py), and returning final PDFs with a completion checklist.

## Summary

- The **ai-job-search codebase structure** follows a thin-pointer architecture separating AI workflows, portal integrations, and user data
- **Workflow definitions** live in `.claude/` including skill manifests, command specifications, and security settings
- **Job portal integrations** reside in `.agents/skills/` with standardized CLI contracts for Danish and global job boards
- **Document generation** relies on LaTeX templates in `cv/` and `cover_letters/` with ATS verification via [`tools/verify_pdf.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/verify_pdf.py)
- **User materials** are isolated in `documents/` and tracked via `job_search_tracker.csv`, enabling private fork workflows

## Frequently Asked Questions

### What is the purpose of the [`.claude/settings.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/settings.json) file?

The [`.claude/settings.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/settings.json) file serves as the permission manifest for the Claude Code runtime. It explicitly lists which tools the AI agent may invoke, such as `Read`, `Glob`, and `WebFetch`, enforcing the repository's thin-pointer security model by restricting system access to declared capabilities only.

### How does the repository handle different job portals uniformly?

Each job portal integration in `.agents/skills/` implements a common contract defined in its respective [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) file. This contract requires implementing `search` and `detail` commands, maintaining an `enabled:` configuration flag, and supporting multiple output formats including JSON, table, and plain text. The `/scrape` command auto-discovers these skills and executes them through a standardized interface.

### Where is sensitive candidate data stored in the ai-job-search codebase?

Sensitive candidate data resides in the `documents/` folder and the generated [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) file. The repository architecture intentionally separates this user-specific content from shared automation logic, allowing users to maintain private forks containing personal data while continuing to pull updates from the upstream MadsLorentzen/ai-job-search repository.

### What testing infrastructure ensures the reliability of automation commands?

The `tests/` directory contains comprehensive pytest suites covering unit and integration tests for all commands and tools. For example, [`test_apply_records_application.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/test_apply_records_application.py) validates that the `/apply` command correctly records application metadata, ensuring CI reliability and preventing regression in the job application pipeline.