AutoRpa/docs/superpowers/plans/2026-08-10-state-center-web-state-machine.md

State Center Web State Machine Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build the browser-based Web state machine for state_center: job list, timeline, task list, and task/node actions.

Architecture: Keep the existing FastAPI backend as the source of truth for workflow state. Add small, focused backend endpoints for timeline, jobs, tasks, and dev ingestion, then build a React/Vite frontend that only renders backend-computed state and posts actions back. Do not move business rules into the frontend.

Tech Stack: Python 3.13, FastAPI, Pydantic, pymysql, pytest, Node.js, Vite, React, TypeScript, plain CSS.

---

Task 1: Add backend task/timeline data contracts

Files:

• Modify: state_center/sql/schema.sql

• Modify: state_center/app/main.py

• Create: state_center/tests/test_web_state_machine.py

• Step 1: Write the failing test

Add tests for:

• GET /api/jobs/{job_id}/timeline returns all 13 nodes with backend-computed statuses.

• POST /api/tasks/{task_id}/submit stores submitted_result_json and returns the stored result on duplicate submitToken.

• POST /api/jobs/{job_id}/items rejects unsafe replace-after-match behavior.

• Step 2: Run test to verify it fails

Run: python -m pytest state_center/tests/test_web_state_machine.py -v Expected: fail because endpoints/fields do not exist yet.

• Step 3: Write minimal implementation

Add the schema column for stored task results, then implement the backend helpers and endpoints in main.py.

• Step 4: Run test to verify it passes

Run: python -m pytest state_center/tests/test_web_state_machine.py -v Expected: pass.

• Step 5: Commit

git add state_center/sql/schema.sql state_center/app/main.py state_center/tests/test_web_state_machine.py
git commit -m "feat: add web state machine backend contracts"

Task 2: Add browser-ready frontend app

Files:

• Create: state_center_web/package.json

• Create: state_center_web/vite.config.ts

• Create: state_center_web/index.html

• Create: state_center_web/src/main.tsx

• Create: state_center_web/src/App.tsx

• Create: state_center_web/src/api/client.ts

• Create: state_center_web/src/components/JobList.tsx

• Create: state_center_web/src/components/JobTimeline.tsx

• Create: state_center_web/src/components/TaskList.tsx

• Create: state_center_web/src/styles.css

• Step 1: Write the failing test

Add a lightweight frontend build check and a small unit test for timeline status mapping.

• Step 2: Run test to verify it fails

Run: npm test Expected: fail because the app does not exist yet.

• Step 3: Write minimal implementation

Create the Vite app, route-less operational UI, and fetch-based API client.

• Step 4: Run test to verify it passes

Run: npm test Expected: pass.

• Step 5: Commit

git add state_center_web
git commit -m "feat: add web state machine frontend"

Task 3: Wire local dev workflow

Files:

• Create: state_center_web/README.md

• Modify: state_center/README.md

• Step 1: Write the failing test

Not required; this task is documentation and run instructions only.

• Step 2: Write minimal implementation

Document the start commands for the FastAPI backend and Vite frontend on Windows/macOS.

• Step 3: Verify manually

Start backend and frontend locally, open the browser app, and confirm the timeline and task list render.

• Step 4: Commit

git add state_center/README.md state_center_web/README.md
git commit -m "docs: add web state machine runbook"