headquarter/docs/development/setup.md

Development Setup Guide

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+
• Redis 7+
• Git

Quick Setup

1. Clone Repository

git clone https://github.com/your-org/headquarter.git
cd headquarter

2. Backend Setup

cd apps/api

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# Install dependencies
pip install -e ".[dev]"

# Copy environment file
cp .env.example .env
# Edit .env with your settings

3. Frontend Setup

cd apps/web

# Install dependencies
npm install

# Copy environment file
cp .env.example .env
# Edit .env with your settings

4. Database Setup

# Start PostgreSQL and Redis
# (Using Docker or local installation)
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=headquarter postgres:15
docker run -d -p 6379:6379 redis:7

# Create database
createdb headquarter

# Run migrations
cd apps/api
alembic upgrade head

# (Optional) Seed data
python -m src.scripts.seed

5. Start Development Servers

Terminal 1 - Backend:

cd apps/api
source .venv/bin/activate
python -m uvicorn src.main:app --reload --port 8000

Terminal 2 - Frontend:

cd apps/web
npm run dev

Terminal 3 - (Optional) Authentik:

# If using local Authentik
docker compose -f docker-compose.authentik.yml up -d

Development Environment Variables

Create apps/api/.env:

APP_ENV=development
DATABASE_URL=postgresql+asyncpg://headquarter:headquarter@localhost:5432/headquarter
REDIS_URL=redis://localhost:6379/0
SESSION_SECRET=dev-session-secret-change-me
API_DOMAIN=localhost
WEB_DOMAIN=localhost

# Authentik (optional for local dev)
AUTHENTIK_DOMAIN=authentik.local
AUTHENTIK_CLIENT_ID=headquarter-web
AUTHENTIK_CLIENT_SECRET=change-me
AUTHENTIK_APPLICATION_SLUG=headquarter-web

Create apps/web/.env:

VITE_API_BASE_URL=http://localhost:8000

IDE Setup

VS Code Extensions

Recommended extensions:

• Python (ms-python.python)
• Pylance (ms-python.vscode-pylance)
• ESLint (dbaeumer.vscode-eslint)
• Prettier (esbenp.prettier-vscode)
• TypeScript Importer (pmneo.tsimporter)

PyCharm/IntelliJ

1. Open apps/api as project
2. Set Python interpreter to .venv
3. Enable Django/Flask support for FastAPI

Debugging

Backend Debugging

VS Code launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: FastAPI",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": ["src.main:app", "--reload", "--port", "8000"],
      "jinja": true,
      "justMyCode": true
    }
  ]
}

PyCharm:

1. Run → Edit Configurations
2. Add Python configuration
3. Module name: uvicorn
4. Parameters: src.main:app --reload --port 8000

Frontend Debugging

VS Code launch.json:

{
  "type": "chrome",
  "request": "launch",
  "name": "Launch Chrome against localhost",
  "url": "http://localhost:5173",
  "webRoot": "${workspaceFolder}/apps/web/src"
}

Common Tasks

Database Migrations

cd apps/api

# Create new migration
alembic revision --autogenerate -m "description"

# Run migrations
alembic upgrade head

# Downgrade
alembic downgrade -1

# Current version
alembic current

# History
alembic history

Adding Dependencies

Backend:

cd apps/api
# Add production dependency
pip install package-name
# Add to pyproject.toml [project.dependencies]

# Add dev dependency
pip install -e ".[dev]"
# Add to pyproject.toml [project.optional-dependencies.dev]

Frontend:

cd apps/web
npm install package-name
npm install -D package-name  # dev dependency

Git Workflow

1. Create feature branch: git checkout -b feature/name
2. Make changes
3. Run quality gates (see below)
4. Commit: git commit -m "feat: description"
5. Push: git push origin feature/name
6. Create Pull Request

Project Structure

headquarter/
├── apps/
│   ├── api/                 # Backend (FastAPI)
│   │   ├── src/
│   │   │   ├── api/         # API routes
│   │   │   ├── auth/        # Authentication
│   │   │   ├── models/      # Database models
│   │   │   ├── utils/       # Utilities
│   │   │   └── main.py      # Entry point
│   │   ├── tests/           # Test suites
│   │   ├── alembic/         # Migrations
│   │   └── pyproject.toml   # Dependencies
│   └── web/                 # Frontend (React)
│       ├── src/
│       │   ├── api/         # API clients
│       │   ├── components/  # React components
│       │   ├── pages/       # Page components
│       │   └── styles/      # CSS
│       └── package.json     # Dependencies
├── docs/                    # Documentation
├── docker-compose.yml       # Dev setup
└── Makefile                 # Common commands

Troubleshooting

Database Connection Errors

# Check PostgreSQL is running
pg_isready -h localhost -p 5432

# Check credentials
psql postgresql://headquarter:headquarter@localhost:5432/headquarter -c "SELECT 1"

Port Conflicts

# Find process using port 8000
lsof -i :8000

# Kill process
kill -9 <PID>

Node Modules Issues

cd apps/web
rm -rf node_modules package-lock.json
npm install

Python Environment Issues

cd apps/api
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Resources

• FastAPI Documentation
• React Documentation
• SQLAlchemy Documentation
• Alembic Documentation