# DeepAudit Agent Instructions

This guide provides essential technical information for agentic coding tools operating within the DeepAudit repository.

## 🛠 Development Commands

### Backend (Python/FastAPI)
Located in `/backend`. Uses `uv` for environment management and `pytest` for testing.

- **Sync Environment:** `uv sync`
- **Start Server:** `uvicorn app.main:app --reload`
- **Run All Tests:** `pytest`
- **Run Agent Tests:** `python tests/agent/run_tests.py`
- **Run Single Test:** `pytest tests/agent/test_agents.py::test_name`
- **Linting:** `ruff check .`
- **Formatting:** `black .`
- **Type Checking:** `mypy .`
- **Database Migrations:** `alembic upgrade head`

### Frontend (React/TypeScript)
Located in `/frontend`. Uses `pnpm` and `Vite`.

- **Install Dependencies:** `pnpm install`
- **Start Dev Server:** `pnpm dev`
- **Build Project:** `pnpm build`
- **Linting:** `pnpm lint`
- **Format:** `pnpm format`
- **Type Checking:** `pnpm type-check`

---

## 🎨 Code Style & Conventions

### General
- **Language:** English for code (variables, functions, comments), though some documentation/logs may be in Chinese.
- **Architecture:** Follow the Multi-Agent architecture. Backend logic for agents is in `backend/app/agents/`.

### Backend (Python)
- **Style:** PEP 8 via `black` (100 char limit) and `ruff`.
- **Typing:** Strict type hinting is required. Use Pydantic models for data validation in `backend/app/schemas/`.
- **Imports:**
  - Standard library first.
  - Third-party libraries second.
  - Local application imports last (using `app.xxx` absolute paths).
- **Naming:** `snake_case` for variables/functions, `PascalCase` for classes.
- **Error Handling:** Use custom exceptions where appropriate. FastAPI's `HTTPException` for API responses. Prefer `logger.error` over `print`.
- **Database:** SQLAlchemy 2.0 (async). Models in `backend/app/models/`.

### Frontend (React/TypeScript)
- **Framework:** React 18+ with Vite and TypeScript.
- **State Management:** Zustand for stores.
- **UI Components:** Shadcn/UI (Radix UI) + Tailwind CSS.
- **Structure:**
  - `src/features/`: Domain-specific components and logic.
  - `src/components/ui/`: Shared low-level components.
  - `src/shared/`: Cross-cutting concerns (hooks, types, utils, api).
- **Types:** Define interfaces in `src/shared/types/index.ts`. Avoid `any`.
- **Imports:** Use absolute paths (e.g., `@/components/...` if configured, otherwise relative to `src`).
- **Naming:** `PascalCase` for components, `camelCase` for hooks and utilities.
- **Formatting:** Use Biome for linting and formatting.

---

## 🤖 Agent Framework specifics
- **Core Agents:** Orchestrator, Recon, Analysis, Verification.
- **Tools:** Agents use specialized tools (e.g., `sandbox_exec` for PoC verification, `semgrep_scan`, `rag_query`).
- **Sandbox:** PoC execution happens in isolated Docker containers (`docker/sandbox`).
- **RAG:** Uses ChromaDB for vector storage and Tree-sitter for intelligent code chunking.
- **Agent Logic:** Implementation resides in `backend/app/services/agent/agents/` and tools in `backend/app/services/agent/tools/`.

## 📁 Repository Structure
- `backend/app/agents/`: Agent logic.
- `backend/app/api/`: API endpoints.
- `frontend/src/features/`: Frontend modules.
- `docker/`: Deployment and sandbox configurations.
- `rules/`: Custom audit rules.