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.
   • This is resolved from a local prototype timestamp or a Git SHA.
2. The server loads the PVC for the specific component instance.
3. The FCS evaluator merges them.
   • PVC values override FCS defaults.
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.

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
• links to the selected template/prototype

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.