Refinery Studio

OctoMesh Data Refinery Studio (Angular)

Purpose

Developer guide for working in octo-frontend-refinery-studio — the main Angular web application for OctoMesh. The Studio is a unified workspace for three audiences:

• Developers — design Construction Kits (CK), configure data models, build integrations
• Data owners — build dashboards (MeshBoards), define queries, manage data pipelines
• End users — interactive dashboards, real-time visualizations, KPIs

This is NOT the old admin panel. octo-frontend-admin-panel is the legacy interface. New frontend feature work belongs in Refinery Studio.

CRITICAL: where the app actually lives

The git repo root (C:\dev\meshmakers\octo-frontend-refinery-studio) is not the npm project. The app package is one level down:

octo-frontend-refinery-studio/
└── src/
    └── octo-mesh-refinery-studio/   ← the Angular app (package.json, codegen.yml, src/)

Run all npm/ng commands from src/octo-mesh-refinery-studio/. There is no root-level package.json.

Tech Stack (verified from package.json)

Other notable deps: monaco-editor (YAML/code editing), dockview-angular (dock layouts), cytoscape + dagre (graph views), cron-parser/cronstrue (schedule UIs), tus-js-client (resumable uploads), @microsoft/signalr.

CK construction-kit terms: CK = schema (CkTypeDto, CkEnumDto, CkRecordDto, CkAttributeDto); Rt = data instances (RtEntityDto with rtId, ckTypeId, associations). Use rtCkTypeId (e.g. OctoSdkDemo/Customer) for runtime queries, not fullName.

Commands (verified in package.json — run from src/octo-mesh-refinery-studio/)

npm start/npm run build are prefixed by a setup-license step (scripts/setup-license.js) for the Kendo license — do not bypass it.

Lint/test discipline (from the repo CLAUDE.md — REQUIRED)

Always run the linter after every code change. CI fails on any lint error. Common fixes: unused imports → ng lint --fix; intentionally unused vars → prefix with _; missing types → add explicit annotations.

Pre-commit gate (run from src/octo-mesh-refinery-studio/):

ng lint && npm test -- --watch=false --browsers=ChromeHeadless && ng build --configuration development

If package.json changed (incl. via npm install), regenerate the lock file before committing: rm -f package-lock.json && npm install (CI runs npm install and needs them in sync).

Multi-Tenant Routing

Routes follow the /:tenantId/... pattern. Each tenant gets an isolated Apollo client pointing at that tenant's GraphQL endpoint. Feature areas are lazy-loaded via *.routes.ts:

• repository/ — Runtime Browser, CK Browser, Auto-Increment, Fixup Scripts, Events, Query Builder, Archives
• reporting/ — Report Explorer (folder/file tree)
• identity/ — users, roles, groups, OAuth clients, identity providers
• communication/ — adapters, pools, applications, data flows
• general/, bot/, development/, ui-management/

When adding a feature, register its routes under the relevant parent *.routes.ts with a loadChildren import and a breadcrumb data entry.

OctoGraphQlDataSource Pattern (list views)

The primary list/grid is ListViewComponent (mm-list-view) from @meshmakers/shared-ui. Back it with a directive that extends OctoGraphQlDataSource<T> (from @meshmakers/octo-ui). Verified sketch, condensed from tenants/communication/adapters/data-sources/adapters-data-source.directive.ts:

import { Directive, forwardRef, inject } from "@angular/core";
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';
import { OctoGraphQlDataSource } from '@meshmakers/octo-ui';
import { DataSourceBase, FetchDataOptions, FetchResultTyped, ListViewComponent } from '@meshmakers/shared-ui';
import { GraphQL } from '@meshmakers/octo-services';
import { GetSystemCommunicationAdaptersDtoGQL, GetSystemCommunicationAdaptersQueryDto } from '../../../../graphQL/getSystemCommunicationAdapters';

// Derive the item type from the generated query type (no hand-written DTOs)
type Item = NonNullable<NonNullable<NonNullable<GetSystemCommunicationAdaptersQueryDto['runtime']>['systemCommunicationAdapter']>['items']>[number];
export type AdapterDto = NonNullable<Item>;

@Directive({
  selector: "[appAdaptersDataSource]",
  exportAs: 'appAdaptersDataSource',
  providers: [{ provide: DataSourceBase, useExisting: forwardRef(() => AdaptersDataSourceDirective) }]
})
export class AdaptersDataSourceDirective extends OctoGraphQlDataSource<AdapterDto> {
  private readonly gql = inject(GetSystemCommunicationAdaptersDtoGQL);

  constructor() {
    super(inject(ListViewComponent));
    this.searchFilterAttributePaths = ['name'];   // fields the text box searches
  }

  public override fetchData(options: FetchDataOptions): Observable<FetchResultTyped<AdapterDto> | null> {
    const variables = {
      first: options.state.take,
      after: GraphQL.offsetToCursor(options.state.skip ?? 0),
      sortOrder: this.getSortDefinitions(options.state),
      fieldFilter: this.getFieldFilterDefinitions(options.state),
      searchFilter: this.getSearchFilterDefinitions(options.textSearch)
    };
    return this.gql.fetch({ variables, fetchPolicy: "network-only" }).pipe(map(result =>
      new FetchResultTyped<AdapterDto>(
        result.data?.runtime?.systemCommunicationAdapter?.items?.filter(i => i !== null) as AdapterDto[] || [],
        result.data?.runtime?.systemCommunicationAdapter?.totalCount ?? 0
      )));
  }
}

Key points:

• The base class supplies getSortDefinitions, getFieldFilterDefinitions, getSearchFilterDefinitions — use them; do not hand-roll Kendo state parsing.
• Always fetchPolicy: "network-only" for live list data.
• Derive DTO types from the generated query type; never duplicate the shape.
• Wire it on the template via the directive selector and exportAs: <mm-list-view appAdaptersDataSource #dir="appAdaptersDataSource" ...>.
• Copy ID context menu is REQUIRED on every list/detail view showing Rt entities (submenu: RtId, CkTypeId, RtCkTypeId, RtEntityId). The GraphQL query must select constructionKitType { ckTypeId { fullName } }.

For the full new-list-component checklist (folder layout, routes, mm-list-view inputs, Copy-ID implementation), read references/data-source-and-components.md.

GraphQL Code Generation Workflow

GraphQL operations live in src/app/graphQL/*.graphql. After editing or adding one, run npm run codegen. Config is codegen.yml (verified):

• Generated types get the Dto suffix (typesSuffix: Dto) → RtEntityDto, CkTypeDto, GetSystemCommunicationAdaptersQueryDto, etc.
• near-operation-file preset → one generated .ts per .graphql operation, with shared base types in globalTypes.ts.
• An injectable Apollo Angular service is generated per operation (...DtoGQL, e.g. GetSystemCommunicationAdaptersDtoGQL) — inject it with inject(...).
• possibleTypes.ts (fragment matcher) and scalars: { DateTime: Date } are emitted too.

Never edit generated .ts by hand — edit the .graphql, regenerate. The generated GraphQL folder is excluded from ESLint. Ensure schema.graphql is current before generating.

LCARS Theme System

The Studio uses a Star-Trek-LCARS-inspired theme built from the Octo Brand Manual. src/styles.scss is the single source of truth for theme tokens, global LCARS layout classes, and Kendo overrides.

Two token tiers:

• Brand tokens (theme-invariant) — --octo-mint #64ceb9, --neo-cyan #00a8dc, --royal-violet #6c4da8, --toffee #da9162, --bubblegum #ec658f, etc. Use these for decorative accents (header bar, footer ribbon).
• Semantic theme tokens (--theme-*) — --theme-bg-app, --theme-bg-surface, --theme-text-primary, --theme-text-secondary, --theme-text-accent, --theme-border-subtle, --theme-glow-primary, --theme-status-success/warning/error/info, --theme-chart-1..8. These have dark defaults and light overrides; use them for anything that must adapt to dark/light mode.

Dark is default; light auto-applies on prefers-color-scheme: light unless the user forces a theme via the AppBar toggle (ThemeService writes <html data-theme="…">, persisted in localStorage key octo-theme-preference).

Do / Do-not (from repo CLAUDE.md)

• Do use var(--theme-bg-*), var(--theme-text-*), var(--theme-border-*) for theme-dependent values, and var(--octo-mint) etc. for brand accents.
• Do use color-mix(in srgb, var(--brand) X%, transparent) for alpha derivations.
• Do NOT redeclare brand color SCSS vars at the top of a component's SCSS — styles.scss owns them.
• Do NOT duplicate the global LCARS layout classes (.lcars-page-header, .lcars-content-panel, .lcars-footer, .footer-bar, etc.) in component SCSS — they are global. Component SCSS should hold only the container class (background gradient), responsive padding, and component ::ng-deep overrides.
• Do NOT use pure black — the darkest background is Deep Sea #07172b.
• Every page-level component MUST use the standard LCARS layout (header / content panel / footer). Library components stay theme-agnostic; LCARS styling is the host app's job.

For the full token catalog, page-layout HTML/SCSS template, and component-author conventions, read references/lcars-theme.md.

Shared Libraries — octo-frontend-libraries

The @meshmakers/* packages are developed in the separate octo-frontend-libraries repo and consumed here, not via an npm-link script. In package.json they are file: references into the sibling repo's built dist:

"@meshmakers/octo-ui": "file:../../../octo-frontend-libraries/src/frontend-libraries/dist/meshmakers/octo-ui"

(CI/Docker swaps these file: refs for registry versions before install.)

To change a shared library, edit and build it in octo-frontend-libraries (per-library script, e.g. npm run build:octo-ui, which runs ng lint && ng build), then re-run npm install here to pick up the updated dist/. Clear the Angular cache if stale: npx ng cache clean. Keep @angular/* versions aligned across both repos or npm install hits ERESOLVE peer conflicts.

Backend for local UI dev

The Studio needs running OctoMesh services. To stand up a meshtest tenant with sample data (commands run via octo-cli, which must be on PATH):

octo-cli -c Create -tid meshtest -db meshtest        # create tenant (Mutating)
./om_importck.ps1 -configuration Debug               # import sample CKs
./om_importrt_sample_general.ps1                      # optional runtime data
./om_importrt_sample_simulation.ps1                   # optional simulation feed

For building/starting the backend services and infrastructure, defer to the octo-devtools skill.

Common Pitfalls (from the repo CLAUDE.md)

• Running npm/ng from the repo root — there is no package.json there; use src/octo-mesh-refinery-studio/.
• Editing generated GraphQL .ts files by hand instead of the .graphql source + npm run codegen.
• Forgetting npm run codegen after touching a .graphql file (build then references a missing/old ...DtoGQL).
• Skipping ng lint — CI fails on any lint error; unused imports and untyped vars are the usual culprits.
• Hand-writing DTO interfaces instead of deriving from generated query types.
• Duplicating global LCARS classes or brand color vars in component SCSS.
• Mismatched @angular/* versions between this repo and octo-frontend-libraries → ERESOLVE on install.
• Omitting the Copy-ID context menu (and its constructionKitType query field) on Rt entity list/detail views.

References

• references/data-source-and-components.md — new list-component checklist, mm-list-view inputs, OctoGraphQlDataSource details, Copy-ID context menu, CK detail-inline conventions.
• references/lcars-theme.md — brand + semantic token catalog, page-layout HTML/SCSS template, light-theme tokens, Kendo overrides, component-author conventions.