HarborForge/README.md

# HarborForge

Agent / human collaborative task-management platform — manages the full
proposal → milestone → task lifecycle with strict state machines, plus a
CLI, monitoring, and OpenClaw integration.

## Repository layout

This is the umbrella repository; every component is a git submodule:

```
HarborForge/
├── AbstractWizard/             # Go, secure first-time setup service (SSH tunnel, port 8080)
├── HarborForge.Backend/        # Python/FastAPI, core REST API + RBAC (port 8000)
├── HarborForge.Frontend/       # React + TypeScript + Vite single-page app (port 3000)
├── HarborForge.Cli/            # Go command-line client `hf`
├── HarborForge.Monitor/        # Go host telemetry client (optional local bridge 9100)
├── HarborForge.OpenclawPlugin/ # Node OpenClaw plugin `harbor-forge`
├── HarborForge.Test/           # Integration tests (backend pytest / frontend Playwright)
├── docker-compose.yml          # Docker orchestration
├── nginx-host.conf.example     # Host nginx config example
└── .env.example                # Environment variable template
```

## Quick start

```bash
# Clone and initialize all submodules
git clone --recurse-submodules https://git.hangman-lab.top/zhi/HarborForge.git
cd HarborForge
# If already cloned without submodules:
git submodule update --init --recursive

# Configure environment (do NOT use the defaults — see "Security")
cp .env.example .env
# Edit .env: set at minimum a strong random SECRET_KEY and DB passwords

# Start the services
docker compose up -d
```

## First deployment — setup wizard

HarborForge uses [AbstractWizard](./AbstractWizard) for secure
initialization. The wizard listens on `127.0.0.1` only and must be
reached over an SSH tunnel.

```bash
# 1. SSH tunnel: forward the wizard port to your machine
ssh -L 18080:127.0.0.1:18080 user@your-server

# 2. Open the frontend in a browser (or via the host nginx).
#    If the backend is not initialized, it redirects to the setup wizard.

# 3. In the wizard, configure: database connection, admin account,
#    default project (optional).

# 4. Once saved, the backend detects the config and starts; refresh
#    the page → login screen.
```

### Startup flow

```
docker compose up
  ├── mysql    → database starts
  ├── wizard   → AbstractWizard starts (127.0.0.1, SSH-tunnel access)
  ├── backend  → blocks waiting for the config file (polls /config/harborforge.json)
  └── frontend → checks backend state
                 ├── backend not ready → shows the setup wizard (SSH tunnel to wizard)
                 └── backend ready     → normal login screen
```

### Security model

- The wizard port binds to `127.0.0.1` and is never exposed to the
  external network; initialization must be done over an SSH tunnel.
- Config is shared with the backend via a Docker volume (never over the
  network); the backend mounts it read-only.

## Deployment architecture

```
Host nginx (80/443)
  ├── /     → frontend (Docker, port 3000)
  └── /api/ → backend  (Docker, port 8000)

Internal to Docker (not exposed):
  wizard (127.0.0.1) → config management, SSH-tunnel access
  wizard_config vol  → written by wizard, read-only for the backend
  mysql (127.0.0.1)  → data persistence
```

## Submodules

| Submodule | Stack | Role |
|-----------|-------|------|
| [AbstractWizard](./AbstractWizard) | Go | First-time setup wizard; atomic config writes + backups; init/readonly modes |
| [HarborForge.Backend](./HarborForge.Backend) | Python / FastAPI / SQLAlchemy / MySQL | Core API: users, projects, tasks, milestones, proposals, RBAC, webhooks, worklogs, notifications |
| [HarborForge.Frontend](./HarborForge.Frontend) | React 18 / TS / Vite | SPA, ~20 pages; auto-detects an uninitialized backend → setup wizard |
| [HarborForge.Cli](./HarborForge.Cli) | Go | Permission-aware command-line client `hf` |
| [HarborForge.Monitor](./HarborForge.Monitor) | Go | Standalone host telemetry client, heartbeat reporting |
| [HarborForge.OpenclawPlugin](./HarborForge.OpenclawPlugin) | Node / TS | OpenClaw plugin; bridges telemetry; can install the `hf` skills and calendar scheduling |
| [HarborForge.Test](./HarborForge.Test) | pytest / Playwright | Backend and frontend integration tests |

## Core domain model

- **Milestone**: `open → freeze → undergoing → completed` (freeze
  requires exactly one release task)
- **Task** (issue / story / test / maintenance / research / review /
  resolution): `pending → open → undergoing → completed`; completion
  requires a comment
- **Proposal**: a user proposes → a manager accepts → a feature-story
  task is auto-created in a milestone; rejected proposals can reopen
- **RBAC**: fine-grained permissions + a project role hierarchy
  (guest < viewer < member < dev < mgr < admin)

## Ports

| Service | Container port | Bind | Env var |
|---------|----------------|------|---------|
| Frontend | 3000 | see compose | `FRONTEND_PORT` |
| Backend  | 8000 | see compose | `BACKEND_PORT` |
| MySQL    | 3306 | 127.0.0.1   | `MYSQL_PORT` |
| Wizard   | 8080 | 127.0.0.1   | `WIZARD_PORT` |

> The SSH-tunnel example uses local port `18080` forwarding to the
> server-side wizard.

## Security

Before deploying, you must:

- **Set a strong random `SECRET_KEY`** (e.g. `openssl rand -hex 32`).
  The backend refuses to start on a weak/default/short key.
- Not use the placeholder passwords from `.env.example`; set a strong
  MySQL password.
- Never commit a `.env` containing real secrets.

The backend's auth / RBAC / SSRF hardening is documented in the
"Security" section of the
[HarborForge.Backend README](./HarborForge.Backend).

## Frontend

The frontend uses a centralized custom design system (the industrial
"Foundry Deck" theme); see the
[HarborForge.Frontend README](./HarborForge.Frontend) for details.