HarborForge Project Plan

Overview

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?