headquarter/docs/development.md

Development Guide

Prerequisites

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

Installation

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

cp .env.example .env

Copy the frontend environment example:

cp apps/web/.env.example apps/web/.env

Running Locally

Frontend only

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

Backend only

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

Both (via root script)

pnpm dev        # Runs frontend and backend in parallel

With Docker Compose

docker compose up --build -d

Testing

Frontend

pnpm --filter @headquarter/web test

Uses Vitest + Testing Library + jsdom.

Backend

pnpm --filter @headquarter/api test

Or directly with pytest:

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

All tests

make test
# or
pnpm test

Linting and Type Checking

Frontend

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

Backend

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

All

make lint
make typecheck

Building

make build
# or
pnpm build

Project Layout

├── apps/
│   ├── web/          # Vite React TypeScript frontend
│   └── api/          # FastAPI Python backend
├── docs/             # Documentation
├── deploy/           # Deployment skeleton files
├── docker-compose.yml
└── 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.