# Purpose of the `src` Directory in ai-job-search: Modular CLI Architecture

> Discover the purpose of the src directory in ai-job-search. It houses modular CLI architecture for LinkedIn, Jobnet, and Freehire, enabling automated job searches with business logic and API wrappers.

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

---

**The `src` directory in ai-job-search contains the TypeScript source code that implements standalone command-line interfaces (CLIs) for each job portal agent, housing the business logic, commands, API wrappers, and parsing utilities required to automate job searches across platforms like LinkedIn, Jobnet, and Freehire.**

The ai-job-search repository organizes its automation capabilities through modular agent skills, where the purpose of the `src` directory is to serve as the command center for portal-specific operations. Located within the hidden `.agents/skills/{portal-name}/cli/` hierarchy, these directories transform high-level workflow instructions defined in `.claude/` files into executable commands for scraping and querying job listings.

## Location and Structure of the `src` Directory

Each job portal integration exists as a separate skill with its own `src` folder under `.agents/skills/`, followed by the portal identifier and `/cli/src/`. For example, the LinkedIn agent resides at `.agents/skills/linkedin-search/cli/src/`, while the Jobnet agent uses `.agents/skills/jobnet-search/cli/src/`. This separation ensures that portal-specific scraping logic remains isolated and maintainable.

### Standard Internal Layout

Every `src` directory follows a consistent architectural pattern that supports the Bun runtime:

- **[`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts)** – The entry point that defines the CLI interface, argument parsing, and command routing.
- **`commands/`** – Individual command modules including [`search.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/search.ts), [`detail.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/detail.ts), and [`occupations.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/occupations.ts), each encapsulating specific operations like querying listings or retrieving job details.
- **`helpers/`** – Reusable utilities for HTTP fetching, HTML parsing, rate limiting, and data normalization (e.g., [`apiFetch.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/apiFetch.ts), [`parseJobCards.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/parseJobCards.ts)).
- **`types/`** – TypeScript interfaces and type definitions for API responses, job objects, and command option schemas.
- **`tests/`** – Unit and integration tests validating CLI behavior, typically located alongside the source files.

## Core Implementation Files

The `src` directories house all business logic that powers the automated job-search agents, while higher-level orchestration merely invokes these standalone CLIs. This architecture keeps concerns separated and allows each portal integration to function independently.

### Entry Point: [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts)

In each skill's [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts) file—such as [`.agents/skills/linkedin-search/cli/src/cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.agents/skills/linkedin-search/cli/src/cli.ts)—the command-line interface is constructed for Bun execution. This file bootstraps the argument parser and dispatches to the appropriate command handler, enabling patterns like `bun run src/cli.ts search [options]`.

### Command Modules

The `commands/` subdirectory contains operation-specific implementations that handle distinct user intents:

- **[`search.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/search.ts)** – Processes job queries across all supported portals, handling parameters like query strings (`-q`), locations (`-l`), job age filters (`--jobage`), and output formats (`--format`).
- **[`detail.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/detail.ts)** – Retrieves comprehensive job posting information using unique identifiers, such as fetching a specific Jobnet listing by UUID.
- **[`occupations.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/occupations.ts)** – Lists available job categories and occupations for platforms like Freehire, supporting filtering via `--search-string` and pagination via `--per-page`.

### Helper Utilities

Reusable scraping and API logic resides in `helpers/` to prevent code duplication across commands:

- **[`parseJobCards.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/parseJobCards.ts)** (LinkedIn) – Extracts structured job data from HTML responses, processing card elements into standardized objects.
- **[`apiFetch.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/apiFetch.ts)** (Jobnet, Jobbank) – Manages authenticated HTTP requests, response handling, and error normalization for JSON-based APIs.
- **[`htmlFetch.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/htmlFetch.ts)** (Freehire) – Handles raw HTML retrieval for subsequent parsing operations.
- **[`parseSearchPage.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/parseSearchPage.ts)** (Jobindex) – Processes search result pages into iterable job listings.

## Executing Commands from the `src` Directory

Practical usage requires running TypeScript files directly through Bun, targeting the specific skill's [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts) entry point. The `src` directory structure supports immediate execution without separate compilation steps.

Searching LinkedIn for backend positions:

```bash
bun run .agents/skills/linkedin-search/cli/src/cli.ts search \
    -q "backend engineer" \
    -l "Remote" \
    --jobage 30 \
    --format table

```

Fetching detailed job information from Jobnet using a specific job ID:

```bash
bun run .agents/skills/jobnet-search/cli/src/cli.ts detail 9ef43bce-d82b-4ea1-a098-7ff6520f99be \
    --format json

```

Querying occupations through Freehire with pagination:

```bash
bun run .agents/skills/freehire-search/cli/src/cli.ts occupations \
    --search-string "sygeplejerske" \
    --per-page 5

```

## Portal-Specific Source Implementations

The repository maintains dedicated `src` directories for each integrated job portal, each containing similar structural patterns but portal-specific implementation details:

**LinkedIn Search**
- **Key files:** [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts), [`commands/search.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/commands/search.ts), [`helpers/parseJobCards.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/helpers/parseJobCards.ts)
- **Path:** `.agents/skills/linkedin-search/cli/src/`

**Jobnet Search**
- **Key files:** [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts), [`commands/search.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/commands/search.ts), [`helpers/apiFetch.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/helpers/apiFetch.ts)
- **Path:** `.agents/skills/jobnet-search/cli/src/`

**Freehire Search**
- **Key files:** [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts), [`commands/search.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/commands/search.ts), [`helpers/htmlFetch.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/helpers/htmlFetch.ts)
- **Path:** `.agents/skills/freehire-search/cli/src/`

**Jobindex Search**
- **Key files:** [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts), [`commands/search.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/commands/search.ts), [`helpers/parseSearchPage.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/helpers/parseSearchPage.ts)
- **Path:** `.agents/skills/jobindex-search/cli/src/`

**Jobbank Search**
- **Key files:** [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts), [`commands/search.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/commands/search.ts), [`helpers/apiFetch.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/helpers/apiFetch.ts)
- **Path:** `.agents/skills/jobbank-search/cli/src/`

## Summary

- The `src` directory in ai-job-search acts as the implementation layer for TypeScript-based CLI agents, located at `.agents/skills/{portal}/cli/src/`.
- Each directory isolates portal-specific business logic through standardized subdirectories: `commands/` for operation handlers, `helpers/` for utilities, and `types/` for TypeScript definitions.
- Entry points in [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts) enable direct Bun execution: `bun run .agents/skills/linkedin-search/cli/src/cli.ts`.
- This modular architecture separates scraping concerns from workflow orchestration, allowing independent development, testing, and maintenance of each job portal integration.

## Frequently Asked Questions

### Where is the `src` directory located in ai-job-search?

The `src` directory resides within each agent skill at `.agents/skills/{skill-name}/cli/src/`, where `{skill-name}` represents specific portals such as `linkedin-search`, `jobnet-search`, `freehire-search`, `jobindex-search`, or `jobbank-search`.

### What programming language is used in the `src` directories?

All `src` directories contain **TypeScript** source code executed through the Bun runtime. This includes the main entry point [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts), command modules like [`search.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/search.ts) and [`detail.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/detail.ts), and helper utilities such as [`apiFetch.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/apiFetch.ts) and [`parseJobCards.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/parseJobCards.ts).

### How do I run commands using files in the `src` directory?

Execute commands by targeting the skill's [`cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli.ts) entry point with Bun. For example: `bun run .agents/skills/linkedin-search/cli/src/cli.ts search -q "data engineer" -l "Berlin, Germany" --format table`. The CLI arguments are passed directly to the TypeScript implementation in [`src/cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/src/cli.ts).

### Why does each job portal have its own `src` directory?

This separation isolates portal-specific scraping logic, API wrappers, and authentication mechanisms. It enables developers to add new job portals without affecting existing implementations, and allows the repository to treat each integration as a standalone CLI tool that can be invoked independently or composed into larger automated workflows.