cbuserguide Workflow & State Machine

Data Model

App (e.g., "cbapp")
└── Version (e.g., "1.0.0") ← one active at a time
    └── Module (e.g., "admin-users", "admin-settings")
        └── Artifacts
            ├── screenshots/
            │   ├── users_list.png
            │   └── users_new.png
            └── markdown/
                ├── users.md
                └── settings.md

State Machine

                    ┌─────────────────────────────────────────┐
                    │                                         │
                    ▼                                         │
┌──────────┐    ┌──────────────┐    ┌─────────────┐    ┌───────────┐
│   INIT   │───▶│  GENERATING  │───▶│  VALIDATING │───▶│ PUBLISHED │
└──────────┘    └──────────────┘    └─────────────┘    └───────────┘
     │                 │                   │                  │
     │                 │                   │                  │
     └─────────────────┴───────────────────┴──────────────────┘
                              reset

States:
- INIT:       Module created, no artifacts yet
- GENERATING: Screenshots and/or markdown being generated
- VALIDATING: Artifacts ready for human review
- PUBLISHED:  Approved and live

State Transitions (API)

From	To	Endpoint	Trigger
INIT	GENERATING	POST /modules/{id}/generate	Start generation
GENERATING	VALIDATING	(automatic)	Generation complete
VALIDATING	PUBLISHED	POST /modules/{id}/publish	Human approval
VALIDATING	GENERATING	POST /modules/{id}/regenerate	Request changes
ANY	INIT	POST /modules/{id}/reset	Start over

Module Configuration

{
  "id": "admin-users",
  "name": "User Management",
  "paths": ["/users", "/users/new", "/users/{id}"],
  "generation_options": {
    "screenshots": {
      "auto": true,
      "manual": false
    },
    "markdown": {
      "auto": true,
      "manual": false
    }
  },
  "state": "init",
  "artifacts": {
    "screenshots": [],
    "markdown": []
  }
}

API Endpoints

Apps

• GET /api/apps - List apps
• POST /api/apps - Create app
• GET /api/apps/{app_id} - Get app details

Versions

• GET /api/apps/{app_id}/versions - List versions
• POST /api/apps/{app_id}/versions - Create version
• PUT /api/apps/{app_id}/versions/{v}/activate - Set active version

Modules

• GET /api/versions/{v_id}/modules - List modules
• POST /api/versions/{v_id}/modules - Create module
• GET /api/modules/{id} - Get module details
• PATCH /api/modules/{id} - Update module config
• DELETE /api/modules/{id} - Delete module

State Transitions

• POST /api/modules/{id}/generate - INIT → GENERATING
• POST /api/modules/{id}/publish - VALIDATING → PUBLISHED
• POST /api/modules/{id}/regenerate - VALIDATING → GENERATING
• POST /api/modules/{id}/reset - ANY → INIT

Artifacts

• GET /api/modules/{id}/screenshots - List screenshots
• GET /api/modules/{id}/markdown - List markdown files
• GET /api/artifacts/{artifact_id} - Get artifact content
• POST /api/modules/{id}/screenshots/upload - Manual upload
• POST /api/modules/{id}/markdown/upload - Manual upload

Generation Options UI (Placebo Checkboxes)

┌─────────────────────────────────────────────────┐
│ User Management Module                          │
├─────────────────────────────────────────────────┤
│                                                 │
│ Screenshots                                     │
│ ┌─────────────────────────────────────────────┐ │
│ │ [x] Auto-generate    [ ] Manual upload      │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Markdown Documentation                          │
│ ┌─────────────────────────────────────────────┐ │
│ │ [x] Auto-generate    [ ] Manual upload      │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ [ Generate ]  [ Reset ]                         │
└─────────────────────────────────────────────────┘

Directory Structure

output/
└── cbapp/
    └── 1.0.0/                    # version
        ├── admin-users/          # module
        │   ├── screenshots/
        │   │   ├── users_list.png
        │   │   └── users_new.png
        │   └── markdown/
        │       └── users.md
        └── admin-settings/
            ├── screenshots/
            │   └── settings_*.png
            └── markdown/
                └── settings.md

Workflow Example

1. Create App: POST /api/apps → {"name": "cbapp", "base_url": "https://testsite.nominate.ai"}

2. Create Version: POST /api/apps/cbapp/versions → {"version": "1.0.0"}

3. Create Module: POST /api/versions/1/modules →

   {
     "name": "admin-users",
     "paths": ["/users", "/users/new"],
     "generation_options": {"screenshots": {"auto": true}, "markdown": {"auto": true}}
   }
   

4. Generate: POST /api/modules/1/generate

5. Triggers Playwright crawler for screenshots
6. Triggers AI for markdown generation

7. State: INIT → GENERATING → VALIDATING

8. Review: Human views artifacts at /api/modules/1/screenshots and /api/modules/1/markdown

9. Publish or Regenerate:

10. Happy: POST /api/modules/1/publish → PUBLISHED
11. Changes needed: POST /api/modules/1/regenerate → GENERATING