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

├── 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

# 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

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 for details on running these checks locally.

Documentation

• Architecture — System design and MVP phases
• Development — Local setup and day-to-day commands
• Deployment — Portainer/Traefik assumptions
• Deploy Skeleton — 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:

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