Headquarter

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

Current Status

This repository is an initial scaffold (FN-002). It provides:

• React + Vite + TypeScript frontend (apps/web)
• FastAPI + Python backend (apps/api)
• 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
├── 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

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 — RunFusion executable environment proof of concept
• FN-009 — Persistent config and secrets handling
• FN-010 — code-server manifest and spawn flow

License

TBD