619 Developing 04328026

# 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.