# Developer Guide

> The most convenient way to configure the Python environment is to use

- Skill: `tools-only/developer-guide-13` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/developer-guide-13`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/developer-guide-13/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/developer-guide-13

---

# Developer Guide

## Architecture Documentation

- **[Architecture Overview](architecture/OVERVIEW.md)** - System components, research flow, and module responsibilities
- **[Database Schema](architecture/DATABASE_SCHEMA.md)** - Database models and relationships
- **[Extension Guide](developing/EXTENDING.md)** - How to add custom search engines, strategies, and LLM providers
- **[Testing and CI](CI_CD_INFRASTRUCTURE.md)** - GitHub Actions workflows, pre-commit hooks, and security scanning

## Configuring the Environment

The most convenient way to configure the Python environment is to use
[PDM](https://pdm-project.org/en/latest/). After installing PDM, configure the
environment and install dependencies:

```bash
pdm install --no-self
```

You can run a command in the environment by prefixing it with `pdm run`. You
can also activate the environment with `pdm venv activate`.

## Setting up Pre-Commit Hooks

These hooks will automatically run linting for every commit. You need to
initialize them once after configuring the environment:

```bash
pre-commit install
pre-commit install-hooks
```

# Running the Application

You can run the application directly using Python module syntax:

```bash
# Activate the environment.
pdm venv activate
# You need to be in the src directory if you are not.
cd src

# Run the web interface
python -m local_deep_research.web.app
# Run the CLI version
python -m local_deep_research.main
```

# Building a Package

To build a wheel and source distribution, simply run `pdm build`.

# Building Frontend Assets

If you're developing from source and want to use the Web UI, you need to build the frontend assets:

```bash
npm install
npm run build
```

This builds the Vite frontend into `src/local_deep_research/web/static/dist/`.

> **Note:** pip users don't need this step - pre-built assets are included in the PyPI package.