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

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

### 2. Backend Setup

```bash
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

```bash
cd apps/web

# Install dependencies
npm install

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

### 4. Database Setup

```bash
# 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:
```bash
cd apps/api
source .venv/bin/activate
python -m uvicorn src.main:app --reload --port 8000
```

Terminal 2 - Frontend:
```bash
cd apps/web
npm run dev
```

Terminal 3 - (Optional) Authentik:
```bash
# If using local Authentik
docker compose -f docker-compose.authentik.yml up -d
```

## Development Environment Variables

Create `apps/api/.env`:

```bash
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`:

```bash
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**:
```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**:
```json
{
  "type": "chrome",
  "request": "launch",
  "name": "Launch Chrome against localhost",
  "url": "http://localhost:5173",
  "webRoot": "${workspaceFolder}/apps/web/src"
}
```

## Common Tasks

### Database Migrations

```bash
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**:
```bash
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**:
```bash
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

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

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

### Port Conflicts

```bash
# Find process using port 8000
lsof -i :8000

# Kill process
kill -9 <PID>
```

### Node Modules Issues

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

### Python Environment Issues

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

## Resources

- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [React Documentation](https://react.dev/)
- [SQLAlchemy Documentation](https://docs.sqlalchemy.org/)
- [Alembic Documentation](https://alembic.sqlalchemy.org/)