Nebula Frontend Consultant

Architecture — Three Clean Layers

Designer-Frontend/src/
├── infra/           ← Infrastructure: APIs, shared components, auth, i18n, config, Redux
├── presentation/    ← UI layer: pages, hooks, helpers, routes, constants
├── services/        ← Business logic: API connectors, Zustand stores, GraphQL
├── types/           ← TypeScript type definitions
└── utils/           ← Shared utilities

This is a clean separation. Infrastructure provides the plumbing (HTTP clients, auth wrappers, component registry). Presentation owns the UI (canvas editor, page management, property panels). Services connect to the backend and manage state.

The UIDL System — How Pages Work

Every page in Nebula Studio is a tree of JSON metadata objects. Understanding this structure is fundamental to answering any question about the platform.

Page Hierarchy (Strict)

container (root)
  └── row
       └── column (col: "1"-"12")
            └── UI controls (Textbox, Button, Table, etc.)

You cannot place a control directly inside a container — it must be container → row → column → control. This is enforced by the canvas editor.

Control Identity

Every control gets two IDs at drop time:

• id: "ID" + Date.now() + Math.floor(Math.random() * 1000) — timestamp-based
• controlId: UUID v4 via uuidv4() — globally unique

Layout — 12-Column Responsive Grid

"layout": {
  "colLayout": {
    "lg": { "col": "12", "height": "200" },
    "md": { "col": "12", "height": "200" },
    "sm": { "col": "12", "height": "200" }
  }
}

• col is a string ("1" through "12"), not a number
• height is also a string
• Breakpoints: sm (<576px), md (≥768px), lg (≥992px), xl (≥1200px), plus a col fallback
• Rows support alignItems and justifyContent within colLayout.lg

controlType Casing — The Critical Gotcha

controlType values are not Nb-prefixed. They use plain names, but the casing is inconsistent:

• lowercase: button, container, row, column, tab, cardcontainer, listview, heatmap
• PascalCase: Textbox, Textarea, Numeric, Checkbox, DatePicker, Table, Panel, Accordion, etc.
• camelCase: datePicker, dateTimepicker, dateRangePicker, dialogModal, radiogroup, buttongroup

The exact casing must come from ComponentsRef.ts or the ControlComponent enum — never guess.

→ For the full controlType registry, read references/component-registry.md

Special Children Patterns

Most containers use a children array. Three controls differ:

Complex Config Objects

Several controls require nested config objects:

• Panel → panelConfig (header with avatar, badges, action icons, menu)
• Accordion → accordionConfig (header with menu items, footer)
• Stepper → stepperConfig (prev/next/skip buttons, step data with fragments)
• MenuButton → menuButtonConfig (menu items, badges, paragraph, icons)
• DialogBox → dialogProperties (type: sidedraw/modal, size, header/footer)
• Popover → popoverTemplate array

Metadata Lifecycle

metadataDefinition.json (405KB schema for all controls)
  ↓ parsed by
metadataDefinition.ts → prepareMetadata() → componentsDefinition map
  ↓ cloned on
Component Drop (WorkArea.tsx) → assigns unique id + controlId
  ↓ stored in
useMetaDataStore (Zustand) → setMetaData() / addChildComponent()
  ↓ updated by
InspectWindow (Property Panel) → updateControlMetadataById()
  ↓ rendered by
RenderControl.tsx → ComponentReference[controlType].element

State Management — Zustand Stores

Nebula Studio uses multiple Zustand stores with clear domain separation:

The key store for most questions is useMetaDataStore — it manages the entire component tree:

• setMetaData(updatedMetaData, item) — replace the tree
• setSelectedComponent(id) — canvas selection
• addChildComponent(metadata, parentId, subDropArea?) — add a control
• updateControlMetadataById(controlMetadata) — property panel edits
• removeComponent(id) / duplicateComponent(id) — delete/clone
• setPageVariables(metaData, queryEvents, dataQueries) — compute exposed variables

REST API

The backend sits at ${RIDS_API_URL}/v1/api/2/. Authentication is Bearer token via the RIDS auth system.

→ For the full endpoint reference, read references/api-endpoints.md

Key endpoint groups:

• Pages: CRUD + metadata write (POST /page/metadata is the primary import endpoint)
• Modules: CRUD + versioning + page listing
• Applications: CRUD + versioning + publishing
• Data Queries: Bulk CRUD + execution
• Data Sources: CRUD + versioning
• Variables: Module-scoped variable management
• Versioning: Draft → Publish workflow
• Tags & Audit: Tagging system + version comparison

Milkyway Pipeline Context

Nebula Studio is the Phase 6 import target of the Milkyway pipeline. The pipeline converts Lovable-generated output into UIDL JSON and imports it via the REST API:

1. POST /application        → create or find app    → appId
2. POST /module             → create or find module  → moduleId
3. POST /page               → create page            → pageId
4. POST /page/metadata      → import UIDL JSON       → page populated
5. POST /page/version       → create draft version
6. (manual) designer reviews and publishes

The UIDL pipeline must:

• Produce the exact JSON structure described above (not React code)
• Use controlType strings that match ComponentsRef.ts exactly
• Enforce container → row → column → control nesting
• Handle special cases (Tab object children, ListView fieldDefs, CardContainer template)
• Validate output against metadataDefinition.json

→ For controlType mapping from Nb components, read* references/component-registry.md

Key Source Files

Application Pages

The designer has these main areas:

How to Answer Questions

When someone asks about Nebula Studio:

1. Architecture questions — Explain the three-layer structure, point to specific files, describe how data flows from the JSON schema through stores to the rendered canvas
2. UIDL / metadata questions — Reference the hierarchy rules, controlType casing, layout grid format, and special children patterns. If they need specific controlType info, point them to the component registry reference
3. API questions — Reference the endpoint groups and the import sequence. If they need exact endpoint paths, read the API endpoints reference
4. State management questions — Explain the Zustand store separation, key methods, and which store owns what
5. Milkyway / import questions — Walk through the 6-step import sequence, emphasize controlType matching, hierarchy enforcement, and validation against metadataDefinition.json
6. Component questions — Distinguish between the React component (@ramco-platform/studio-components) and the UIDL controlType. The Nb* prefix exists only in React — UIDL uses plain names
7. Styling questions — Reference the SCSS token system (typography, spacing, shadows, focus, radius) in the design tokens reference

When You Need to Read the Codebase

For questions that go beyond what's in this skill and its references, read the actual source files at /Users/admin/Codes/nebula-studio-fe/Designer-Frontend/. The key source files table above tells you where to look. For the 405KB metadataDefinition.json, read only the section relevant to the specific controlType being asked about — don't try to load the whole file.

What to Watch Out For

• Nb prefix confusion*: Lovable and the Milkyway docs sometimes use Nb-prefixed names. The UIDL metadata uses plain names. Always clarify this.
• Casing assumptions: Never guess controlType casing. The registry is the source of truth — button is lowercase but Textbox is PascalCase.
• Layout string types: col and height in colLayout are strings, not numbers. This trips up UIDL generators.
• Tab children aren't an array: They're an object keyed by tab name. This is a common mistake in generated UIDL.
• ListView has no children: It uses fieldDefs. Another common UIDL generation error.
• Redux vs Zustand: New features use Zustand. Legacy features may still use Redux. Don't assume one or the other.