Platform Architecture

This document explains the core architecture concepts behind the HiStruct platform. The most important idea is that every component is defined by two parallel data systems: FCS and PVC.

FCS vs PVC Duality

HiStruct components always combine a definition layer and an instance layer.

Mental model

• FCS = the template
  • Files such as .fcs, .fcscdx, and .fcscdm stored inside an .fcc folder.
  • Describes logic, formulas, geometry generation, reports, views, defaults, and metadata.
• PVC = the instance data
  • The values a user has actually entered or selected.
  • Includes dimensions, options, booleans, list selections, and other per-component state.

A good analogy is:

• FCS behaves like a class definition.
• PVC behaves like object instance fields.

The template can be reused thousands of times, but each component instance has its own PVC.

How Rendering Works

When a component is evaluated, the platform combines FCS and PVC in a fixed order:

1. The server loads the FCS definition from the prototype source.
   • For a component this is the Git commit pinned when the component was created (or a local prototype timestamp during development).
2. The server loads the PVC for the specific component instance.
3. The PVC is converted to an updater and applied to the root FCS object.
   • PVC values replace the matching := inputs; everything else keeps the FCS definition.
4. The evaluator produces outputs.
   • Computed expressions
   • 3D geometry
   • Parameter state
   • Reports
   • View data

FCS template + PVC instance state -> evaluated component output

Override behavior

The important rule is:

FCS provides the default structure and logic, while PVC provides the current user state.

For example, if Inputs.fcs defines a default roof width of 4.0, but the user changes it to 4.5 in the UI, the evaluator uses 4.5 from PVC.

Commit Pinning, Determinism and Caching

A component's state is exactly two things: its PVC and the commit of its template that was current when the component was created.

• When a user creates a component from a palette item, the platform takes the current commit of the palette's repo/branch and stores it with the component. Later commits affect only components created afterwards.
• Moving an existing component to a newer commit is an admin service action, done when the template's inputs are known to be compatible. Users cannot do it. Copying a component copies its commit too. That works as a workaround, but it is not a supported process.
• Commits are immutable and FCS is pure and deterministic. The same commit and the same PVC therefore always produce the same scene, report and values. The platform uses hash(commit) + hash(PVC) as a cache key, and a cached result is served without starting an engine.
• On a cache miss the server fetches the commit if needed, compiles/analyses the FCS, converts the PVC to an updater, evaluates the requested output and caches it.
• The engine keeps backward compatibility for old commits (including E3 quirks), so components created years ago still load. New behaviour is always opt-in, through .fcsconfig.json or new syntax.

Consequences for template authors:

• Pushing to the palette branch is effectively a release: the next component someone creates uses it. HiStruct behaves like a CI/CD pipeline.
• Do not casually rename or remove inputs (PVC paths). Existing components stay safe on their old commit, but they can no longer be moved forward without a migration. Under E4, updating a field that no longer exists is an error.

PVC in the API

Several API fields expose PVC snapshots during editing workflows.

OriginalPvcB64

Base64-encoded PVC snapshot before edits are applied.

Use cases:

• change detection
• optimistic concurrency checks
• comparison against the current edited state

StagingEditedPvcB64

Base64-encoded PVC that includes pending, not-yet-committed edits.

Use cases:

• client-side staging
• previewing edits before commit
• incremental form updates

ComponentEditTransaction

Endpoint used to commit PVC changes.

This is the server-side write step that turns staged parameter changes into the current persisted component instance state.

Spaces

HiStruct organizes content into spaces.

Examples:

• deve-rv-local
• sky

A space is a logical container for:

• component palettes
• component instances
• users and roles
• environment-specific templates and permissions

Space route key

The space key is part of normal application routing:

/{spaceKey}/{lang}/...

Examples:

deve-rv-local/en/...
sky/en/...

What belongs to a space

Each space typically has its own:

• palette definitions
• accessible templates
• created components
• developer/admin capabilities
• role assignments

This means the same .fcc template can be published differently in different spaces.

Component Lifecycle

A component moves through several stages from authoring to evaluation.

1. Author FCS code

Developers create or modify component files locally or in GitHub.

Typical files include:

• Main.fcs
• Inputs.fcs
• Pvc.fcs
• Views.fcscdx
• fcscdm.json

2. Register the component template in a space palette

The template is added to the palette for a target space so users can create instances from it.

3. Users create component instances

A user selects a palette item and creates a new component. At that point, the system creates:

• a component record
• an initial PVC
• a link to the template pinned to the current commit of the palette's branch

4. Booster evaluates FCS + PVC

A Booster node performs the compute-heavy work. This can run locally or in cloud infrastructure.

Responsibilities include:

• loading the component definition
• evaluating formulas
• generating scenes and report data
• resolving view outputs

5. Results are returned to the app

The final outputs can include:

• 3D scenes
• parameter forms
• evaluated expressions
• printable or downloadable reports

Authorization Model

HiStruct exposes different capabilities depending on role.

Admin

• Full access
• Can use Shift+R refresh behavior
• Can access all admin-only endpoints
• Can refresh prototypes and development resources

SpaceDeveloper

• Can modify palette templates
• Can manage components within a space
• Typically responsible for template rollout inside a specific space

Developer

• Can access developer-oriented features
• Can use the G console and other dev tooling
• Useful for troubleshooting and prototype inspection

Regular user

• Can view and edit their own components
• Normally interacts through standard UI forms and component pages

Permission diagnostic endpoint

The first endpoint to check when permissions look wrong is:

/{space}/{lang}/Model/UserSession

This endpoint is the primary diagnostic surface for:

• current user identity
• effective roles
• session validity
• space-specific permission issues

Technology Stack

HiStruct spans a browser UI, an ASP.NET backend, and distributed compute workers.

Backend

The server handles:

• authentication and authorization
• component and project APIs
• palette management
• PVC persistence
• evaluation orchestration

Frontend

The Aurelia frontend handles:

• navigation
• editing screens
• parameter forms
• scene presentation
• developer features

Compute layer

Booster nodes run evaluation jobs and allow expensive geometry/report generation to scale independently from the web tier.

Storage layer

• Azure Blob stores large static or generated artifacts.
• SQL stores structured data such as components, projects, permissions, and PVC-related metadata.

Realtime communication

SignalR is used for Booster-to-server communication, which helps coordinate job execution and status updates.

End-to-End Summary

A HiStruct component is never just code and never just data.

It is always the combination of:

• FCS: the reusable definition
• PVC: the per-instance state

That duality explains most of the platform architecture:

• why templates live in .fcc folders
• why users edit form values without changing source files
• why prototypes can be refreshed independently of component state
• why the API exposes PVC snapshots during editing workflows

Once this model is clear, the rest of the platform becomes much easier to reason about.