Officeless Studio LOCAL
Branching & CI/CD concept

1. Officeless Studio LOCAL capabilities

Studio is a localhost-only workbench in Deployment Helper. It connects to the active Dev gateway from Gateway settings (stored as GATEWAY_UAT2_*). Environment and company labels are derived from the host (e.g. gateway-uat2.smart-cimb.com → CIMB · UAT2).

Local filesystem layout

officeless-assets/
  visual-programming/{id}.json   # VP
  ui/single/{id}.json            # SEM
  ui/multiple/{id}.json          # MEM
  data-manager/{id}.json         # DM
  manifest.json

flowchart LR
  GW["Dev gateway
e.g. gateway-uat2.smart-cimb.com"]
  CAT["Studio Catalog
VP / SEM / MEM / DM"]
  DISK["Local disk
officeless-assets/"]
  EDIT["Local workspace
/ Full editor"]
  GIT["Local Git repo
branch identity"]

  GW -->|download| CAT
  CAT -->|write JSON + _meta| DISK
  DISK <-->|open / Save| EDIT
  DISK -->|upload / Deploy Dev| GW
  GIT -.->|branch name → GCS identity| EDIT
        

2. Synchronisation mechanism (step by step)

There is no continuous sync. Engineers run explicit hops: Dev → local (download), edit & save locally, then local → Dev (upload / deploy).

1. Confirm Gateway settings: Non-production (Dev) URL + credentials are configured.
2. Open /studio on localhost. Header shows company · environment (e.g. CIMB · UAT2).
3. In the catalog, filter by kind and select the assets you need.
4. Click Download — Studio fetches each item from the Dev gateway APIs and writes JSON under officeless-assets/ with a _meta envelope (kind, id, downloadedAt, source).
5. Local workspace refreshes; new files appear in the explorer (often with a new highlight).
6. Edit visually or as JSON → Save writes back to disk and updates manifest.json.
7. When ready, use Upload to Dev (batch) or Deploy Dev (full editor). Studio strips _meta before calling the gateway set APIs.

sequenceDiagram
  autonumber
  actor Eng as Engineer
  participant UI as Studio UI
  participant API as /api/studio/*
  participant GW as Dev Gateway
  participant FS as officeless-assets/

  Eng->>UI: Select catalog items
  Eng->>UI: Download
  UI->>API: POST /download {ids}
  API->>GW: fetch VP/SEM/MEM/DM
  GW-->>API: asset JSON
  API->>FS: writeLocalAsset (+ _meta)
  API-->>UI: saved paths / counts
  UI->>FS: refresh explorer

  Eng->>UI: Edit + Save
  UI->>API: PUT /local-files/content
  API->>FS: overwrite JSON + manifest

  Eng->>UI: Upload to Dev / Deploy Dev
  UI->>API: POST /local-files or /deploy
  API->>FS: read asset, strip _meta
  API->>GW: set / structure-data set
  GW-->>API: OK
  API->>FS: mark lastUploadedAt
  API-->>UI: success
        

3. Branch strategy & persisting code changes

Studio uses the local Git branch name as the engineer / GCS branch identity. Source-of-truth for edits is the filesystem under officeless-assets/; Git is how the team reviews, shares, and rolls back those files.

How branch identity works

1. Studio reads git rev-parse --abbrev-ref HEAD (or STUDIO_GIT_BRANCH).
2. That name becomes the Studio branch badge (git: feature/…) and GCS path slug.
3. If Git is unavailable, identity falls back to the login / local-dev username.

sequenceDiagram
  autonumber
  actor Eng as Engineer
  participant Git as Local Git
  participant UI as Studio
  participant FS as officeless-assets/
  participant GCS as GCS Studio store

  Eng->>Git: git checkout -b feature/cimb-expense
  Eng->>UI: Open /studio (badge: git: feature/cimb-expense)
  Eng->>UI: Download selected assets
  UI->>FS: write JSON files
  Eng->>UI: Edit + Save local
  UI->>FS: persist changes
  Eng->>Git: git add officeless-assets/... && git commit
  Note over Git: PR / review / CI on branch
  Eng->>UI: Upload to Dev / Deploy Dev
  UI->>GCS: optional branch snapshot (deployed)
        

What to commit

• Commit the specific JSON files you changed under officeless-assets/ (and manifest.json if updated).
• Do not commit gateway passwords or auth tokens.
• Keep PRs small: one business change / selected asset set per branch when possible.

4. Download, upload & rollback

Download and upload are selection-based. Rollback has two levels: Discard (unsaved editor) and Git commit restore (persisted local files).

4.1 Download

1. Catalog tab → choose kind → search/page → check items.
2. Download writes files; Local workspace opens them for editing.
3. Open also downloads; for non-VP it may pull GCS branch state then open the full editor.

4.2 Upload / Deploy

1. Upload tab → select local files → Upload to Dev.
2. Or open full editor → Deploy Dev for the current asset.
3. Payload sent to the gateway excludes Studio _meta so Officeless integrity is preserved.

4.3 Rollback

sequenceDiagram
  autonumber
  actor Eng as Engineer
  participant UI as Studio
  participant FS as Disk
  participant Git as Git history
  participant GW as Dev Gateway

  Note over Eng,UI: Unsaved mistake
  Eng->>UI: Discard
  UI->>UI: Restore last saved buffer
  UI-->>Eng: Message: Discarded unsaved changes

  Note over Eng,Git: Persisted mistake already Saved
  Eng->>Git: git log -- officeless-assets/.../id.json
  Eng->>Git: git checkout <commit> -- path
  Eng->>FS: file restored
  Eng->>UI: Refresh / re-open file
  opt Gateway must match restored content
    Eng->>UI: Upload to Dev / Deploy Dev
    UI->>GW: set asset
  end
        

Suggested Git rollback commands

# Inspect history for one asset
git log --oneline -- officeless-assets/ui/multiple/2h08faPDg.json

# Restore file content from a known commit (keeps working tree change)
git checkout <commit-sha> -- officeless-assets/ui/multiple/2h08faPDg.json

# Or restore entire local assets tree from last good commit
git checkout <commit-sha> -- officeless-assets/

# Then in Studio: Refresh → verify → Upload / Deploy Dev if needed

5. Selected code promotion (integrity)

Promotion in Studio LOCAL means pushing only the assets you selected to the Dev gateway — not a blind full-environment sync, and not Tentacles cross-env hops.

Integrity rules

• Selection gates: catalog checkboxes for download; upload checkboxes for promote.
• Kind isolation: VP / SEM / MEM / DM use dedicated fetch/set endpoints.
• _meta envelope: local bookkeeping only; stripped before gateway write.
• JSON validation: Save rejects invalid JSON before writing disk.
• Branch identity: deploy associates work with the current Git branch for traceability.
• Conflict awareness: pull may warn when other open GCS branches exist for the same item.

flowchart TD
  A["Catalog / Local file list"] --> B{"User selects
specific ids?"}
  B -->|No| Z["No download / no upload"]
  B -->|Yes| C["Read only selected assets"]
  C --> D{"Direction"}
  D -->|Download| E["Fetch from Dev gateway"]
  E --> F["Write selected JSON + _meta"]
  D -->|Upload / Deploy| G["Strip _meta"]
  G --> H["Validate payload"]
  H --> I["Gateway set for those ids only"]
  I --> J["Mark lastUploadedAt / branch deployed"]
  F --> K["Local workspace available"]
  J --> L["Dev runtime updated
unselected assets untouched"]
        

6. Engineer checklist (CIMB discussion)

1. Set Dev gateway in Gateway settings; confirm badge shows expected company · env (e.g. CIMB · UAT2).
2. git checkout -b feature/… before downloading.
3. Download only required assets from the catalog.
4. Edit in Local workspace or Full editor → Save local often.
5. Commit JSON changes; open PR for review.
6. Upload / Deploy Dev for the selected set after approval.
7. If wrong: Discard (unsaved) or git checkout <sha> -- path then re-upload if needed.

flowchart LR
  A[Feature branch] --> B[Select + Download]
  B --> C[Edit + Save local]
  C --> D[Git commit / PR]
  D --> E[Upload / Deploy Dev]
  C -.->|unsaved| X[Discard]
  D -.->|bad commit| Y[git checkout file]
  Y --> E