# Understanding the File Structure of UditAkhourii/adhd: A Complete Guide

> Explore the UditAkhourii/adhd file structure. Understand the modular TypeScript architecture, separation of concerns, and key directories like src, documentation, and tests for efficient development.

- Repository: [Udit Akhouri/adhd](https://github.com/UditAkhourii/adhd)
- Tags: how-to-guide
- Published: 2026-07-30

---

**The UditAkhourii/adhd repository follows a modular TypeScript architecture organized into six primary directories—`src/`, `documentation/`, `tests/`, `bench/`, `skills/`, and `docs/`—with a clear separation between the core LLM execution engine, public API surfaces, and supporting infrastructure.**

The `adhd` project is a TypeScript-based library designed for LLM-driven generation workflows. Understanding the file structure of UditAkhourii/adhd reveals a component-oriented layout where type definitions, engine logic, and CLI interfaces are cleanly isolated, making the codebase easy to navigate and extend.

## Top-Level Directory Layout

The repository root organizes functionality into distinct logical buckets. Rather than flattening all code into a single folder, the maintainer separated concerns using the following hierarchy:

```

adhd/
├─ src/                     – Core library code
├─ documentation/           – Guides, design docs, and usage notes
├─ tests/                   – Test suite (Jest)
├─ bench/                   – Benchmarking utilities and data
├─ skills/adhd/             – Skill definition used by the engine
├─ docs/                    – Generated documentation assets
├─ .github/                 – CI/CD workflow definitions
├─ package.json             – NPM package metadata
├─ tsconfig.json            – TypeScript compiler configuration
├─ README.md                – Project overview
└─ LICENSE                  – MIT license

```

This structure ensures that source code, user documentation, and evaluation tools live in separate namespaces, preventing circular dependencies and simplifying automated testing pipelines.

## Core Source Code Organization (`src/`)

The `src/` directory contains the executable TypeScript source that defines the library's behavior. Files here follow a specific dependency flow: **type definitions → core engine → helpers → public entry points**.

### Entry Points and Public API ([`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts))

The file [`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts) serves as the central export hub for the entire package. It re-exports the primary public API consumed by downstream users:

- **`run`** – Orchestrates the LLM-driven generation process
- **`renderText`** – Converts a `RunResult` into a human-readable string
- **`FRAMES`** and **`selectFrames`** – Provide the prompt templates that guide LLM behavior

When you import from `"adhd"` in your own projects, you are targeting the symbols defined in this file.

### Execution Engine ([`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts))

Located at [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), the **engine** contains the core `run` implementation. This module iterates over selected frames, builds LLM query options using `buildQueryOptions` (imported from [`llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/llm.ts)), invokes the model via `callLLM`, parses JSON responses with `parseJSON`, and aggregates everything into a `RunResult` object.

The engine acts as the orchestration layer, coordinating between the frame selection logic and the raw LLM communication primitives.

### Frame Management ([`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts))

The [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) file defines a static array named `FRAMES`, where each element represents a prompt template containing system instructions, user prompts, and optional code snippets. The helper function `selectFrames` randomly picks a subset of these templates, optionally favoring "code mode" when that parameter is enabled.

This separation allows the engine to remain agnostic about specific prompt content while the frames file provides the configurational data that shapes LLM behavior.

### LLM Integration ([`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts))

The [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts) module abstracts all communication with large language models. It exports utilities for:

- **Building request payloads** via `buildQueryOptions`
- **Sending requests** through `callLLM`
- **Safely parsing JSON responses** with optional Zod schema validation

By isolating network logic and response handling here, the codebase prevents the engine from directly managing HTTP concerns or validation errors.

### Rendering and CLI ([`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts), [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts))

The [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) file provides formatting utilities that extract fields like `ideas` and `scores` from a `RunResult` and produce tidy strings for CLI or API consumers. Meanwhile, [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) wires these components into a command-line interface, exposing the `adhd run ...` command that reads configuration, executes `run`, and prints rendered output.

### Type Definitions ([`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts))

Centralized type definitions live in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts), declaring interfaces such as `Idea`, `Score`, and `RunResult`. Keeping types in a dedicated file ensures consistency across the engine, LLM utilities, and public API without creating circular import chains.

## Documentation and Testing Infrastructure

### User Guides (`documentation/`)

The `documentation/` directory contains Markdown files offering detailed user guidance:

- [`quickstart.md`](https://github.com/UditAkhourii/adhd/blob/main/quickstart.md) – Getting started guide
- [`install.md`](https://github.com/UditAkhourii/adhd/blob/main/install.md) – Installation instructions
- [`how-it-works.md`](https://github.com/UditAkhourii/adhd/blob/main/how-it-works.md) – High-level architecture overview
- [`frames.md`](https://github.com/UditAkhourii/adhd/blob/main/frames.md) – Explanation of frame concepts
- [`api.md`](https://github.com/UditAkhourii/adhd/blob/main/api.md) – Public API description

These files ensure newcomers can grasp the library's purpose and extend it without diving directly into source code.

### Test Suite (`tests/`)

The `tests/` directory houses the Jest-based test suite. The file [`tests/llm.test.ts`](https://github.com/UditAkhourii/adhd/blob/main/tests/llm.test.ts) verifies LLM utility behavior, including call handling, JSON parsing, and error cases. This location follows standard Node.js conventions, allowing `npm test` to discover specs automatically.

### Benchmarking (`bench/`)

Performance and evaluation tools reside in `bench/`. Key files include:

- [`run-evals.ts`](https://github.com/UditAkhourii/adhd/blob/main/run-evals.ts) – Runs the evaluation harness across different frames
- [`judge.ts`](https://github.com/UditAkhourii/adhd/blob/main/judge.ts) – Implementation for benchmarking judgments
- [`baseline.ts`](https://github.com/UditAkhourii/adhd/blob/main/baseline.ts) – Baseline implementations for comparison

These scripts are essential when swapping LLM back-ends or tuning frame selection algorithms, providing empirical data on execution speed and output quality.

## Supporting Assets and Configuration

### Skill Definitions (`skills/adhd/`)

The [`skills/adhd/SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md) file provides a markdown description of the "adhd" skill used by the engine. This metadata allows the system to understand available capabilities without hard-coding descriptions into TypeScript.

### Generated Documentation (`docs/`)

The `docs/` folder contains generated assets such as [`index.html`](https://github.com/UditAkhourii/adhd/blob/main/index.html) and `hero.png`. These are build artifacts produced from the source documentation, served as static HTML for GitHub Pages or similar hosting.

### CI/CD Configuration (`.github/`)

The `.github/workflows/` directory stores GitHub Actions pipelines for continuous integration, automated testing, and CodeQL security scanning.

### Package Configuration

Root-level configuration files include [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json) for NPM metadata, [`tsconfig.json`](https://github.com/UditAkhourii/adhd/blob/main/tsconfig.json) for TypeScript compiler settings, [`README.md`](https://github.com/UditAkhourii/adhd/blob/main/README.md) for project overview, and `LICENSE` for the MIT license terms.

## Practical Usage Examples

Below are runnable TypeScript examples demonstrating how the file structure translates into API usage.

### Running with Default Frames

```typescript
import { run, renderText } from "adhd";

async function demo() {
  const result = await run({
    // Minimal required options; defaults will select random frames
    prompt: "Generate ideas for improving focus."
  });
  console.log(renderText(result));
}

demo().catch(console.error);

```

### Selecting Specific Frames and Customizing LLM Options

```typescript
import { run, selectFrames, FRAMES } from "adhd";
import { LLMOptions } from "adhd";

async function customRun() {
  // Pick three frames that include code snippets
  const frames = selectFrames(3, true);
  const llmOpts: LLMOptions = {
    model: "gpt-4",
    temperature: 0.7,
    maxTokens: 500
  };

  const result = await run({
    frames,
    llmOptions: llmOpts,
    prompt: "Suggest a TypeScript function that schedules Pomodoro sessions."
  });

  console.log(result);
}

customRun().catch(console.error);

```

### Command-Line Interface

Once installed globally, you can invoke the CLI directly:

```bash
adhd run --prompt "List quick tactics for staying on task during a meeting."

```

The CLI internally calls the same `run` function exported from [`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts) and prints output formatted by [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts), providing a consistent interface between programmatic and shell usage.

## Summary

- The **file structure of UditAkhourii/adhd** separates core logic (`src/`), user documentation (`documentation/`), and evaluation tools (`bench/`/`tests/`) into distinct top-level directories.
- **[`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts)** defines the public API surface, re-exporting `run`, `renderText`, and frame utilities.
- **[`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)** orchestrates the execution flow, delegating LLM communication to [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts) and frame selection to [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts).
- **[`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)** centralizes TypeScript interfaces to prevent circular dependencies across the codebase.
- **Configuration and metadata** (package.json, tsconfig.json, LICENSE) reside at the repository root, while `.github/workflows/` manages CI/CD automation.
- The modular layout supports both library consumers importing TypeScript functions and end-users running CLI commands.

## Frequently Asked Questions

### What is the main entry point of the UditAkhourii/adhd library?

The main entry point is **[`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts)**, which re-exports the public API including the `run` function, `renderText` formatter, and frame utilities (`FRAMES` and `selectFrames`). When you install the package via NPM and import from `"adhd"`, the module resolver loads this file.

### How does the engine.ts file interact with llm.ts?

The **[`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)** module imports helper functions from **[`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts)** to handle LLM communication. Specifically, the engine calls `buildQueryOptions` to construct request payloads, `callLLM` to execute the network request, and `parseJSON` to safely deserialize responses. This abstraction keeps the engine focused on orchestration while [`llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/llm.ts) manages HTTP and validation concerns.

### Where are the frame definitions stored in the repository?

Frame definitions reside in **[`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts)**, which exports a static array named `FRAMES`. Each frame object contains prompt templates (system and user messages) and optional code snippets. The `selectFrames` function in the same file provides logic for randomly selecting a subset of these templates, optionally weighting toward code-inclusive frames.

### What testing framework does UditAkhourii/adhd use?

The repository uses **Jest** for testing, with test files located in the **`tests/`** directory. The primary test file [`tests/llm.test.ts`](https://github.com/UditAkhourii/adhd/blob/main/tests/llm.test.ts) validates LLM utility behavior, JSON parsing, and error handling. Configuration for Jest is typically defined in [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json) or a standalone [`jest.config.js`](https://github.com/UditAkhourii/adhd/blob/main/jest.config.js) at the repository root.