Workspace State Machine

Every workspace goes through a series of states as you work on content. This diagram shows all possible states and the transitions between them.

stateDiagram-v2
    [*] --> AvailableForSetup: Create workspace

    AvailableForSetup --> InSetup: Start conversation
    Merged --> InSetup: Start conversation

    InSetup --> AvailableForConversation: Setup succeeds
    InSetup --> Problem: Setup fails

    AvailableForConversation --> InConversation: Start conversation

    InConversation --> AvailableForConversation: Finish conversation
    InConversation --> InReview: Send to review
    InConversation --> Problem: Git operation fails

    InReview --> Merged: Reviewer marks merged
    InReview --> AvailableForConversation: Reviewer unlocks

    Problem --> AvailableForSetup: User resets workspace

State Descriptions

AvailableForSetup — Workspace is ready to be set up (initial state or after reset)
InSetup — Workspace is being prepared (cloning, branching)
AvailableForConversation — Workspace is ready for a user to start editing
InConversation — A user is actively working on the workspace
InReview — Changes have been sent for review, PR exists
Merged — The pull request has been merged
Problem — An error occurred that requires manual intervention

Typical Workflow

Here's what happens during a typical content editing session, from selecting a project to having your changes merged.

sequenceDiagram
    participant User
    participant SiteBuilder
    participant GitHub

    User->>SiteBuilder: Select project
    SiteBuilder->>SiteBuilder: Check workspace status

    alt No workspace or needs setup
        SiteBuilder->>GitHub: Clone repository
        SiteBuilder->>GitHub: Create new branch
        SiteBuilder->>SiteBuilder: Run setup steps
    end

    SiteBuilder->>User: Show conversation UI
    User->>SiteBuilder: Make content changes
    SiteBuilder->>GitHub: Commit and push changes

    User->>SiteBuilder: Click "Send to Review"
    SiteBuilder->>GitHub: Create Pull Request
    SiteBuilder->>User: Show PR link

    Note over GitHub: External review process

    GitHub-->>SiteBuilder: PR merged (manual notification)
    SiteBuilder->>SiteBuilder: Mark workspace as Merged

1. Select & Setup

Choose your project. SiteBuilder clones the repository and creates a new branch for your changes.

2. Edit & Commit

Make changes through the chat interface. Each change is automatically committed and pushed to your branch.

3. Review & Merge

Send for review when ready. A pull request is created on GitHub for the review process.

Send to Review Flow

When you click 'Send to Review', several things happen to prepare your changes for the review process.

flowchart TD
    A[User clicks Send to Review] --> B{Uncommitted changes?}
    B -->|Yes| C[Auto-commit with message]
    B -->|No| D{PR already exists?}
    C --> D
    D -->|Yes| E[Use existing PR]
    D -->|No| F{Branch has changes vs main?}
    F -->|Yes| G[Create new PR on GitHub]
    F -->|No| H[Skip PR creation]
    E --> I[Mark conversation FINISHED]
    G --> I
    H --> J[Mark workspace AVAILABLE_FOR_CONVERSATION]
    I --> K[Mark workspace IN_REVIEW]
    K --> L[Show PR link to user]

Important Notes

Any uncommitted changes are automatically committed before sending to review
If a PR already exists for your branch, it will be reused
If your branch has no changes compared to main, no PR is created

Edge Cases & Special Scenarios

Understanding these scenarios will help you know what to expect in less common situations.

Resetting a workspace while in review

What happens if you reset the workspace before the pull request is merged?

sequenceDiagram
    participant User
    participant SiteBuilder
    participant GitHub

    Note over SiteBuilder: Workspace is IN_REVIEW
    Note over GitHub: PR exists for branch ws-abc-123

    User->>SiteBuilder: Reset workspace
    SiteBuilder->>SiteBuilder: Clear branch name
    SiteBuilder->>SiteBuilder: Clear PR URL reference
    SiteBuilder->>SiteBuilder: Set status to AVAILABLE_FOR_SETUP

    Note over GitHub: PR still exists but is now orphaned

    User->>SiteBuilder: Start new conversation
    SiteBuilder->>GitHub: Clone fresh from main
    SiteBuilder->>GitHub: Create NEW branch ws-abc-456
    SiteBuilder->>User: Ready for conversation

    Note over GitHub: Old PR remains open until manually closed

The old PR remains on GitHub but becomes orphaned. You'll need to manually close it. Your next conversation starts with a fresh branch from main.

Multiple users accessing the same workspace

SiteBuilder ensures only one user can actively edit a workspace at a time.

sequenceDiagram
    participant UserA as User A
    participant UserB as User B
    participant SiteBuilder

    UserA->>SiteBuilder: Start conversation
    SiteBuilder->>SiteBuilder: Set workspace IN_CONVERSATION
    SiteBuilder->>UserA: Show conversation UI

    UserB->>SiteBuilder: Try to start conversation
    SiteBuilder->>SiteBuilder: Check workspace status
    SiteBuilder->>UserB: Workspace is busy

    Note over UserA: Working on content...

    UserA->>SiteBuilder: Finish conversation
    SiteBuilder->>SiteBuilder: Set workspace AVAILABLE_FOR_CONVERSATION

    UserB->>SiteBuilder: Start conversation
    SiteBuilder->>UserB: Show conversation UI

The workspace is locked while a user has an active conversation. Other users must wait until the conversation is finished.

Recovering from a PROBLEM state

If a git operation fails, the workspace enters the PROBLEM state. Here's how to recover.

flowchart TD
    A[Git operation fails] --> B[Workspace set to PROBLEM]
    B --> C[Any ongoing conversation marked FINISHED]
    C --> D[User sees error state]
    D --> E{User action}
    E -->|Reset workspace| F[Status set to AVAILABLE_FOR_SETUP]
    F --> G[Next conversation triggers fresh setup]
    G --> H[Clone from main, new branch]
    H --> I[Ready to work again]

    style B fill:#fee2e2,stroke:#dc2626
    style F fill:#dbeafe,stroke:#2563eb
    style I fill:#dcfce7,stroke:#16a34a

What's lost

Any uncommitted local changes that weren't pushed to GitHub.

What's preserved

All commits that were successfully pushed to your branch remain on GitHub.

Reviewer actions and their effects

Reviewers can take two actions on a workspace that's in review. Each has different implications for the next conversation.

flowchart LR
    A[Workspace IN_REVIEW] --> B{Reviewer decision}
    B -->|Mark as Merged| C[Status: MERGED]
    B -->|Unlock| D[Status: AVAILABLE_FOR_CONVERSATION]

    C --> E[Next conversation triggers full setup]
    D --> F[Continue working on same branch]

    style C fill:#dcfce7,stroke:#16a34a
    style D fill:#dbeafe,stroke:#2563eb

Mark as Merged

Use when the PR is merged. Next conversation will start fresh from the updated main branch.

Unlock for Changes

Use to continue working on the same branch. No new setup needed.

External Integrations

SiteBuilder integrates with GitHub for version control. Some operations are automated, while others require manual action.

flowchart TB
    subgraph SiteBuilder [SiteBuilder Application]
        WS[Workspace Management]
        CE[Content Editor]
        RV[Reviewer Dashboard]
    end

    subgraph GitHub [GitHub]
        REPO[Repository]
        BRANCH[Branches]
        PR[Pull Requests]
    end

    WS -->|Clone repository| REPO
    WS -->|Create branch| BRANCH
    CE -->|Commit and push| BRANCH
    CE -->|Create PR| PR
    PR -.->|Manual: Merge PR| REPO
    PR -.->|Manual: Notify merged| RV
    RV -->|Mark as merged| WS

Automated by SiteBuilder

✓ Repository cloning during workspace setup
✓ Branch creation for each workspace
✓ Committing and pushing changes
✓ Creating pull requests when sending to review

Manual / External

⚠ Reviewing and merging pull requests on GitHub
⚠ Notifying SiteBuilder when a PR is merged (reviewer action)
⚠ Closing orphaned PRs after workspace reset

Workflow Documentation