OpenEik · Guide
Apps and suppliers on one model
How Stomra, EikHub, Femra, Varmra and building-product suppliers work on one open model: read a version, work in your own folder, propose, and let a person merge.
The idea: a building like a code base
A code base has many tools around it, each doing its own job on the same files. An OpenEik model is stored the same way, one record per file, with versions, diffs, merges and typed commands, so a building can have many apps around it too.
| In a code base | In an OpenEik project |
|---|---|
| Small source files in one repository | One record per file, in discipline folders |
| Tools check out a commit and do their job | Apps read a version, named by its hash, and do their discipline |
| CI results belong to one commit | Results name the version they were computed from |
| A pull request carries code changes | A proposal carries typed, checked commands |
| Required checks before merge | Checks before merge, such as utilisation ≤ 1.0 for every member |
| Code owners review their paths | Disciplines own their folders |
| "This branch is behind main" | "These results are stale" |
One difference on purpose: the results people rely on are kept inside the model's tree, so they travel with it, on disk, in any git host or with a hosting service.
The apps and the host
| App | What it does | Reads | Writes |
|---|---|---|---|
| Stomra | BIM authoring for people and AI agents; the reference implementation of OpenEik | the whole model, and other apps' files, which it keeps byte for byte | the whole model, every change a checked command |
| Femra | structural analysis by the finite element method, to Eurocode | beams, columns, slabs, walls, roofs, foundations, their types and materials, and the levels | its analysis on its own line beside the building, tied to the version it was computed from; changes to the building only as proposals |
| Varmra | energy balance to the Swedish building regulations | the thermal envelope: exterior walls, windows, doors, roofs, the ground slab, heated storeys, U-values from types and layers | its energy balance and report, in its own folder of the building, tied to the version it was computed from; never the building's records |
EikHub is the host: where buildings branch, get reviewed and merge, the way software does. It keeps the versions, and runs the workflow around them: forks across organisations that remember their origin, proposals with diffs, checks before merge with a green, yellow or red state per element, owners' approvals, and a merge made only by a person, on a confirm page, with a recent sign-in and a signed merge receipt. These are host features, not part of the standard: any host can offer them, and a plain folder with git can follow the same pattern.
The pattern, in six steps
- Read a version. Named by its hash, never "latest". Read only the records you need, and note their hashes.
- Work in your discipline. Your own model, assumptions and software: an analysis, an energy balance, a manufacturability check.
- Write your output under your own folder in the tree, with a manifest naming the version it was computed from.
- Propose changes to the building as typed, checked commands on a line of your own. Never edit another discipline's records.
- A person reviews and merges, with the diff, the checks and the owners' approval.
- Everyone is current. Every app reads the new head; results whose source has changed show as stale until run again.
Steps 1 to 3 touch only the app's own folder. Steps 4 and 5 are the only way the building itself changes.
Results beside the building
An app keeps its work in a folder of its own at the top of the model, named by the app's registered prefix, at a path no building record could have. Building records stay in their discipline folders and change only through commands; derived output such as bodies, drawings, quantities and indexes is rebuilt locally and never committed.
hall-b/
├── eik.json
├── project/ the datums: project, levels, grids, materials
├── types/ architecture/ structure/ … building records
└── femra/frame-a/ Femra's structural analysis
├── model.json source.json members/ loads/ …
├── results/r-5d1c0e9a7b32/manifest.json …
└── proposals/p-b3-deeper.json
A manifest names the version
Every result set carries a manifest. Its computedFrom names the version and a digest of every record the app read, so the file itself says what it belongs to, through an export, a copy or any host.
{
"app": {"name": "femra", "version": "…"},
"computedFrom": {
"inputs": {"count": 41, "digest": "3b0f6c2e…"},
"version": "c3d41f9a…"
},
"kind": "structural-analysis",
"summary": {"maxUtilisation": 0.71}
}
Stale is computed
Hash the records the app read, as they are at the head, and compare with the digest. If one changed, the results are stale, and the tools name the records that changed. Staleness is never written into a file.
Kept small
Per-member extremes, utilisations and summaries, in text files of at most 1 MiB. Meshes and full fields stay out: they are cheap to compute again.
Kept, not merged
The latest set and every signed set stay; history keeps the rest. Results are never merged field by field: take one side and run again on the merged version.
A simplified model, such as a stick model for seismic analysis, lives on a line of its own, and its results belong to that line. What flows back to the main line is never the simplification, only a proposal such as added bracing.
Proposals
A change an app suggests to the building is a proposal of typed commands, each with its precondition (the revision it was made against) and its evidence. Femra, for example, proposes a deeper beam when its design check calls for one:
{
"base": {"version": "e5f6a0b2…"},
"commands": [{
"expectedRevision": 4,
"id": "beam-r8n2wc4d",
"kind": "update",
"patch": {"height": 450, "typeId": "type-beam-450"}
}],
"dryRun": {"ok": true},
"evidence": {"after": 0.86, "before": 1.08, "check": "bending"},
"format": "openeik-proposal/0.1",
"intent": "Deeper B3: bending utilisation 1.08"
}
The reviewer sees the change and its check together. On a host, the checks run on the proposal before merge, and a person merges it. A member of the analysis made from a beam keeps the beam's id, so a result points straight at the element it is about.
Suppliers: propose the real product
Without a shared model, a supplier gets PDFs, re-draws the parts in its own tool, and prices its own reading of the drawings. Deviations surface late, the quote and the drawing drift apart, and comparing bids means comparing PDFs. On OpenEik a supplier works like a contributor to a code base: it is invited in, works in its own copy, checks with its own tools, and proposes the parts it will actually make, with a quote, for the client to review in the model.
- Invite the supplier. By default a supplier reads the whole model, as it would get a complete IFC today. The client may narrow it to some parts, plus what they stand on.
- It reads a named version and finds every part it supplies by category, every railing say.
- It works in its own fork, in its own organisation, and writes only there.
- It checks with its own tool: green, yellow or red per part, with the deviations.
- It opens a proposal: typed commands for the changed elements, with the quote attached.
- The client reviews the diff, the checks and the quote together, in 3D and as text, and merges one.
- The model holds what will be made, and the order names that version.
The diff is the deviation report
Each railing is one record in one file, so a host shows the change per railing and per field. Nothing is re-typed into a deviation list. In this synthetic example a railing supplier's system has a standard height of 1070 mm and mounts on the slab edge:
architecture/level-2/railing/railing-r2h6tq9c.json
"category": "railing",
- "height": 1100,
+ "height": 1070,
"hostId": "slab-b2",
"railing": {
"edges": ["slab-b2:edge:3", "slab-b2:edge:0", "slab-b2:edge:1"],
- "inset": 50
+ "inset": -25,
+ "posts": {"at": [200, 1350, 2500, 3650, 4800]}
},
- "typeId": "type-railing-design-1100"
+ "typeId": "type-railing-supplier-a-1070"
A negative inset puts the railing's line outside the slab edge, as for side mounting, and explicit post positions in millimetres along the line make every tool agree where the posts are. A railing type can also state its mount (side or top) and rectangular posts by width and depth.
Quotes and tenders in the model
A quote is an attachment on the supplier's proposal, tied to the exact version it priced, with a digest of the records it priced: the same mechanism as an app's results. When the architect then moves the balcony's edge, the quote goes out of date by itself, and the host says which records changed.
{
"supplier": "Supplier A",
"pricedVersion": "4f8e2a6b…",
"inputs": {"count": 27, "digest": "b71c09e4…"},
"lines": [
{"marks": ["R-1", "R-4", "R-5", "…"], "type": "type-railing-supplier-a-1100"},
{"marks": ["R-2", "R-7"], "type": "type-railing-supplier-a-1070"}
],
"total": {"amount": 486000, "currency": "SEK"}
}
Competing proposals against the same version make a tender inside the model. The client compares the actual parts in 3D, their checks and their prices side by side. Merging one makes it the model; the others are closed and stay in the record of the tender.
Hidden from each other. During a tender a supplier never sees another supplier's proposal, diff, checks or quote. A quote is visible only to the client's administrators and that supplier, and is not part of the model's shared history. Names and amounts on this page are synthetic.
After the merge, what is ordered is what is drawn. The proposal, its author and the merge are in the history with a signed merge receipt, and if the design moves on, the change shows as a diff against what was ordered, part by part.
Level of detail and what stays private
A proposal can carry any level of detail, and the supplier decides where it sits:
| Level | What it shares |
|---|---|
| Interface only | the exact outer envelope, fixing and connection points, post and fixing positions, clearances, loads on the structure, declared tolerances. Enough for exact clash and layout checks, and nothing about how the part is made |
| Interface and product | plus the visible product, as it will look, for review and rendering |
| Product model | plus the main parts as separate parts, still without fabrication data |
| Full manufacturing model | everything, if the supplier wants. Allowed, never required |
A type states what it provides and what it is authoritative for, so checks know what they may rely on, and nobody mistakes an interface record for shop drawings. Stomra draws a part's declared geometry in place of its derived body.
"declaredGeometry": {
"level": "interface",
"authoritativeFor": ["envelope", "fixings", "clearances", "positions", "loads"],
"envelope": [{"kind": "prism", "…": "…"}],
"tolerances": {"default": 3, "positions": 2}
}
Article numbers, costing and the supplier's own design data stay in its fork, in its own organisation. Its own history stays private too: the client's model receives one squashed merge. Product identity such as system and finish is shared only if the supplier chooses.
Every building part
Invite, fork, check, propose with a quote, review, merge: the flow is the same for every part. What differs is how much of a product the standard's type data can express.
| Part | The supplier's check | The interface it shares |
|---|---|---|
| Railings | system rules, mount, posts | envelope, posts, fixings, loads |
| Windows and doors | sizes, opening, hardware | frame envelope, fixings, opening clearances |
| Roof trusses | span, bearing, loads | truss envelopes, bearing points, loads on walls |
| Steel frames | members and connections | member envelopes, connection points, bolt access |
| Precast elements | production and lifting | element envelope, lifting and connection points, joints |
| Building services | routing, fittings, equipment | equipment envelope, connections, service clearances |
Nine rules for app makers
- Read a named version. Record its hash and the hashes of the records you read.
- Write only your own folder, one item per file, in the stored form; text files of at most 1 MiB.
- Give every result set a manifest, with the version and an inputs digest, the app, the engine and the settings.
- Change the building only by command: typed, dry-run first, with the expected revision, and merged by a person.
- Point at elements by id. Never treat a copy of geometry as the truth.
- Keep what you do not know. Other apps' folders and unknown files stay untouched, byte for byte.
- Keep large fields out. Store extremes and summaries.
- Compute staleness, never store it.
- Never edit building records directly, nor write into a discipline folder.
The standard defines the records, the level-of-detail declaration, the typed commands, the result manifest and the proposal file. A host runs the workflow: proposals between organisations, attachments, supplier access, checks before merge. The two roles are separate on purpose: a supplier's railings are OpenEik records wherever they are hosted.