# Development Guide

## Prerequisites

- **Node.js** ≥ 20 and **pnpm** ≥ 9
- **Python** ≥ 3.11 with `venv` support
- **Docker** and **Docker Compose** (for local services)

## Installation

```bash
# Install Node dependencies and Python virtualenv + packages
make install

# Or manually:
pnpm install
cd apps/api && python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
```

## Environment Setup

Copy the root environment example and fill in local values:

```bash
cp .env.example .env
```

Copy the frontend environment example:

```bash
cp apps/web/.env.example apps/web/.env
```

## Running Locally

### Frontend only

```bash
cd apps/web
pnpm dev        # Vite dev server on http://localhost:5173
```

### Backend only

```bash
cd apps/api
.venv/bin/uvicorn app.main:app --reload --port 8000
```

### Both (via root script)

```bash
pnpm dev        # Runs frontend and backend in parallel
```

### With Docker Compose

> Docker Compose files will be added in Step 5. Once created, run:
>
> ```bash
> docker compose up --build -d
> ```

## Testing

### Frontend

```bash
pnpm --filter @headquarter/web test
```

Uses **Vitest** + **Testing Library** + **jsdom**.

### Backend

```bash
pnpm --filter @headquarter/api test
```

Or directly with pytest:

```bash
cd apps/api && .venv/bin/pytest
```

### All tests

```bash
make test
# or
pnpm test
```

## Linting and Type Checking

### Frontend

```bash
pnpm --filter @headquarter/web lint
pnpm --filter @headquarter/web typecheck
```

### Backend

```bash
pnpm --filter @headquarter/api lint
pnpm --filter @headquarter/api typecheck
```

### All

```bash
make lint
make typecheck
```

## Building

```bash
make build
# or
pnpm build
```

## Project Layout

```text
├── apps/
│   ├── web/          # Vite React TypeScript frontend
│   └── api/          # FastAPI Python backend
├── docs/             # Documentation
├── deploy/           # Deployment skeleton files (added in Step 5)
├── docker-compose.yml (added in Step 5)
└── package.json      # Root monorepo scripts
```

## Conventions

- **Frontend**: React functional components, TypeScript strict mode, ESLint + Ruff-like rules.
- **Backend**: FastAPI, Pydantic settings, pytest, ruff, mypy.
- **Commits**: Conventional commits with task ID prefix, e.g. `feat(FN-002): description`.