# Headquarter

Hosted workspace and tool-orchestration platform where authenticated users create projects, connect Git repositories, and spawn self-hosted tools such as OpenCode and code-server.

## Current Status

This repository provides:

- React + Vite + TypeScript frontend (`apps/web`)
- FastAPI + Python backend (`apps/api`)
- Manifest-driven tool registry with built-in OpenCode and code-server definitions
- Root monorepo tooling (pnpm workspace, Makefile)
- Docker Compose local development stack
- Deployment skeleton for Portainer + Traefik
- Automated tests (Vitest + pytest)

## Repository Layout

```text
├── apps/
│   ├── web/          # React frontend
│   └── api/          # FastAPI backend
├── packages/         # Shared packages (future)
├── docs/             # Architecture, development, and deployment docs
├── deploy/           # Portainer/Traefik deployment examples
├── docker-compose.yml
├── docker-compose.traefik.yml
├── package.json      # Root monorepo scripts
├── Makefile          # Common local workflows
└── .env.example      # Shared environment variables
```

## Prerequisites

- Node.js ≥ 20 and pnpm ≥ 9
- Python ≥ 3.11
- Docker and Docker Compose (optional, for local Postgres)

## Quickstart

```bash
# Install dependencies
make install

# Copy environment examples
cp .env.example .env
cp apps/web/.env.example apps/web/.env

# Run tests
make test

# Start frontend and backend in development mode
make dev
```

### Docker Compose

```bash
docker compose up --build -d
```

This starts the API, web frontend, and PostgreSQL.

## Commands

| Command | Description |
|---------|-------------|
| `make install` | Install Node and Python dependencies |
| `make dev` | Start frontend and backend in parallel |
| `make test` | Run frontend and backend tests |
| `make lint` | Run linters |
| `make typecheck` | Run type checkers |
| `make build` | Build frontend and backend |
| `make compose-up` | Start Docker Compose stack |
| `make compose-down` | Stop Docker Compose stack |

## Continuous Integration

All pull requests and pushes to `main` are validated by a GitHub Actions workflow (`.github/workflows/ci.yml`). The workflow runs the frontend and backend quality gates in parallel:

- **Web CI** — lint, typecheck, and test the React frontend.
- **API CI** — lint with `ruff`, typecheck with `mypy`, and run `pytest` against a PostgreSQL service container.

See [Development](docs/development.md) for details on running these checks locally.

## Documentation

- [Architecture](docs/architecture.md) — System design and MVP phases
- [Development](docs/development.md) — Local setup and day-to-day commands
- [Deployment](docs/deployment.md) — Portainer/Traefik assumptions
- [Deploy Skeleton](deploy/README.md) — Deployment file reference

## Frontend Environment Variables

The frontend (`apps/web`) requires these environment variables:

| Variable | Description |
|----------|-------------|
| `VITE_API_URL` | Backend API base URL |
| `VITE_OIDC_ISSUER` | OIDC provider issuer URL |
| `VITE_OIDC_CLIENT_ID` | OIDC client ID |
| `VITE_OIDC_REDIRECT_URI` | Post-login redirect URL |

Copy `apps/web/.env.example` to `apps/web/.env` and fill in your values.

## Deployment

Deploy to production using Docker Compose:

```bash
# Copy and configure production environment
cp deploy/.env.example deploy/.env
# Edit deploy/.env with your domain and secrets

# Deploy locally for testing
docker compose -f docker-compose.prod.yml up --build -d

# Or deploy via Portainer using deploy/portainer-stack.yml
```

See [Deployment Guide](docs/deployment.md) for full details.

## Scope Boundaries

This scaffold intentionally defers detailed implementation to follow-up tasks:

- **FN-004** — Backend domain models, database migrations, API endpoints, auth integration
- **FN-005** — Frontend dashboard navigation, project creation, authenticated flows
- **FN-006** — Full deployment automation, dynamic Traefik labels for spawned tool containers
- **FN-003** — Manifest-driven tool registry
- **FN-007** — Provider-independent Git connection model
- **FN-008** — OpenCode terminal environment proof of concept
- **FN-009** — Persistent config and secrets handling
- **FN-010** — code-server manifest and spawn flow

## License

TBD