alex
1539a67883
- Replace RunFusion with OpenCode in description - Add frontend environment variables section - Add deployment quick start guide - Update scope boundaries with current task status
139 lines
4.3 KiB
Markdown
139 lines
4.3 KiB
Markdown
# 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
|