HarborForge is a dual UI/automation platform where humans + AI agents operate through a unified issue-driven workflow. The plan below tracks the Python/FastAPI backend, React frontend, and Python CLI, designed to run on a 1 vCPU + 1 GB RAM Docker Compose stack with MySQL persistence.

Workstreams & Task Breakdown

1. Architecture & Platform Foundation

Document system components: API service, React SPA, Python CLI/bot runner, MySQL, webhook dispatcher, optional worker queue.
Define communication contracts (REST+webhook) and env/secret management.
Create Docker Compose template with lightweight images, explicit resource limits, and volumes for logs/database.
Include AbstractWizard initializer as part of deploy script; link to https://git.hangman-lab.top/hzhang/AbstractWizard and capture expectations from its README.
Set up logging/metrics hooks (stdout, log file rotation) and persistence directories on shared volume.

2. Authentication & Role-Based Access

Integrate OIDC standard login flow for UI; CLI uses credential files with no interactive login.
Establish credential lifecycle:
- Credentials have expiry timestamps and remain in DB flagged as expired.
- On usage of expired credential, return new credential + confirmation requirement.
- Confirmation must reach backend within 1 minute.
- Any random reuse of old credential 3–5 times before confirmation results in deletion; future calls require re-authentication (password/OIDC) to issue a new credential.
Store credential files via --creds /path or HARBORFORGE_CREDENTIAL env, support rotation via API.
Define RBAC model per project (roles: admin/dev/mgr/ops); admin user created during initialization.
Build admin-only endpoints/UI/CLI to manage roles, permissions, and project assignments.

3. Core Issue/Work Item Platform

Design issue model that supports multiple types (task/story/test), state transitions, dependencies, tags, priority, comments.
Support multi-account/role membership per project and enforce permission matrix at API layer.
Guarantee every user-facing action can be invoked via API/CLI.
Catalog automation touchpoints (issue lifecycle updates, script triggers, deployment actions) for future extension.

4. Frontend (React)

Define app routes: dashboard, board/list, issue detail, role/project admin, audit/log viewer, automation console.
Implement state management (React Query or equivalent) matching API structure.
Provide UI components for admin role management + webhook configuration.
Surface webhook events and automation status, letting users inspect audit entries.

5. CLI & Automation Surface

Build interactive Python CLI mirroring UI flows; commands are rendered differently but invoke same backend APIs.
CLI uses credential files or env tokens; includes runtime prompts for confirmation when credential rotation occurs.
Bot agent runner polls API for pending automations, executes scripts, and emits callbacks via webhook.
Document CLI command set (issue CRUD, role management, automation triggers, logs) and error handling.

6. API Coverage & Webhooks

Enumerate APIs for all core operations: issues, comments, projects, roles, credentials, automation scripts, audit logs.
Design webhook schema and catalog events to support: issue lifecycle, authentication events, automation/script completion.
Ensure webhook delivery is authenticated and configurable; details to be defined during implementation.
Provide API for credential confirmation flows and for requesting new credentials after deletion.

7. Observability & Logging

Log all API invocations to a file on Docker-mounted volume, capped at 10 MB with rotation.
Keep a webhook audit log (which event, trigger source, response status) for troubleshooting.
Provide endpoints/UI to browse recent logs (within retention threshold).

8. Deployment & Security Posture

Keep ufw locked down on vps.t1 and rely on SSH tunnels (ssh -L) for UI/CLI testing.
Document CLI/agent testing setup (SSH tunnel commands, env vars) so Zhi/Hangman can coordinate.
Outline backup strategy for MySQL data directory within the Compose stack.
Confirm AbstractWizard handles initial admin/project creation; fall back to Zhi if issues arise.

9. Collaboration & Delivery Rhythm

Maintain the new channel with templates for requirements, story cards, milestones, and progress updates.
Use channel to publish deliverables (architecture doc, API spec, deployment instructions, automation scenarios).
Record testing points for UI/CLI without prescribing steps; let Hangman/Zhi define the execution details.

Need any section expanded into user stories or backlog cards next?

README.md Unescape Escape

HarborForge Project Plan

Overview