# brinter-am-technologies-oy/3mf-bio architecture

> Architecture diagram of the GitHub repository brinter-am-technologies-oy/3mf-bio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brinter-am-technologies-oy/3mf-bio
- Repository: https://github.com/brinter-am-technologies-oy/3mf-bio

## Overview

#### Purpose and Entry Points
This repository defines the pre-1.0 **3MF Bio Extension**: an XML schema and reference toolchain for recording biofabrication geometry, biological materials, process, evidence, calibration, maturation, and results inside a 3MF package. Primary user entry points are package validation (`verify.py`, `spec/validate_bio.py`), package generation from mesh plus questionnaire answers (`tools/integrate.py`), and local package inspection (`tools/viewer.html`).

#### Canonical Format Layer
The normative format is the Bio XML Schema and Schematron rules, extending a 3MF model’s `<resources>` section under the Bio namespace. It defines typed resources for evidence, substances, cell populations, bioinks, process, printheads, calibration, regulatory determination, open items, maturation, characterization, protocols, results, and volumetric field bindings.
- `spec/bio.xsd`
- `spec/bio.sch`
- `spec/3MF Bio Extension.md`

The key semantic boundary is that schema validity establishes structural and declared-rule conformance, not truth of scientific or regulatory claims.

#### Validation Pipeline
Validation is intentionally split by capability. XSD validation checks document structure; Schematron checks portable intra-document constraints; Python performs package-aware checks that need ZIP/OPC relationships, external-part existence, bibliography keys, full index bounds, strict/release policy, and cross-part logic.
- `spec/validate_schema.py`
- `spec/validate_bio.py`
- `spec/bio.libxml.xsd`

`validate_bio.py` accepts either an unpacked package directory or `.3mf` ZIP. `--strict` escalates warnings; `--release` rejects any estimated value. `bio.libxml.xsd` is a generated compatibility variant for libxml2/lxml.

#### Provenance, Unknowns, and Release Semantics
The central data-policy model requires numeric values to declare provenance. Estimated values are allowed but must be represented honestly and tied to tracked open items describing ownership and closure actions. This allows the integrator to emit incomplete packages rather than force fabricated inputs; release validation becomes the enforcement boundary.
- `spec/bio.xsd`
- `spec/validate_bio.py`
- `dossier/Parameter-Dossier.md`

Derived process claims additionally require their declared inputs, particularly for extrusion/shear relationships. Acceptance criteria are recorded per laboratory rather than prescribed by the format.

#### Package Authoring and Consumption
The authoring flow is: select a machine profile, generate/fill a questionnaire response, combine it with STL/OBJ geometry, then emit a validating 3MF package. The browser-only viewer reads a local package and prioritizes an operational run sheet, constraints, open items, dossiers, maturation, and geometry; it has no server or upload dependency.
- `tools/questionnaire.py`
- `tools/integrate.py`
- `tools/viewer.html`

Machine-specific capability input is currently represented as JSON profiles, beginning with Brinter.
- `tools/machine_profiles/brinter.json`

#### Reference Packages and Conformance
Two package directories are executable reference data: a volumetric tomographic build and a multi-head extrusion/deposition build with toolpath, biological records, protocols, certificates, and results. They exercise the 3MF OPC structure as well as Bio resources.
- `examples/`
- `examples-extrusion/`
- `examples-extrusion/bio/toolpath/extrusion.gcode`

Conformance testing injects faults through both rule engines; additional round-trip, corpus-generation, red-team, and tool integration checks protect format behavior.
- `spec/conformance_tests.py`
- `spec/roundtrip_test.py`
- `verify.py`

#### Evidence, Review, and Publication Infrastructure
Dossiers hold parameter sources, calibration references, regulatory mapping, bibliography, and fact-check outcomes that support schema vocabulary rather than runtime execution. External review is explicitly scoped to factual/regulatory assessment and collecting a real dataset.
- `dossier/`
- `review/REGULATORY-REVIEW.md`
- `review/DATASET-SHEET.md`

A static documentation/namespace site is generated from repository Markdown and deployed via GitHub Pages. CI validates the repository and publishes the site.
- `site/build_site.py`
- `.github/workflows/validate.yml`
- `.github/workflows/pages.yml`

Main entry points: [`spec/validate_bio.py`](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/validate_bio.py) (Package Validator), [`spec/bio.xsd`](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/bio.xsd) (Bio XML Schema), [`tools/integrate.py`](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/tools/integrate.py) (3MF Integrator), [`verify.py`](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/verify.py) (Repository Verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_format["Canonical Format"]
  node_bio_xsd["Bio XML Schema<br/>normative schema<br/>[bio.xsd]"]
  node_bio_schematron["Bio Schematron<br/>rule set<br/>[bio.sch]"]
  node_format_spec["Extension Specification<br/>format documentation"]
end

subgraph group_validation["Validation"]
  node_libxml_schema["libxml Compatibility Schema<br/>generated schema<br/>[bio.libxml.xsd]"]
  node_schema_validator["Schema Validator<br/>XSD validator<br/>[validate_schema.py]"]
  node_package_validator["Package Validator<br/>package-aware validator<br/>[validate_bio.py]"]
  node_verify["Repository Verification<br/>validation entry point<br/>[verify.py]"]
end

subgraph group_authoring["Authoring &amp; Inspection"]
  node_questionnaire["Questionnaire Generator<br/>authoring tool<br/>[questionnaire.py]"]
  node_machine_profile["Brinter Machine Profile<br/>machine capability data<br/>[brinter.json]"]
  node_integrator["3MF Integrator<br/>package generator<br/>[integrate.py]"]
  node_viewer["Local Package Viewer<br/>browser inspector<br/>[viewer.html]"]
end

subgraph group_references["Reference Packages"]
  node_tomographic_example[("Tomographic Reference Package")]
  node_extrusion_example[("Extrusion Reference Package")]
  node_extrusion_toolpath["Extrusion Toolpath<br/>G-code<br/>[extrusion.gcode]"]
end

subgraph group_evidence["Evidence &amp; Review"]
  node_parameter_dossier["Parameter Dossier<br/>provenance policy"]
  node_dossier[("Evidence Dossiers<br/>supporting records")]
  node_regulatory_review["Regulatory Review<br/>external review scope"]
  node_dataset_sheet["Dataset Sheet<br/>dataset review scope<br/>[DATASET-SHEET.md]"]
end

subgraph group_publication["Publication"]
  node_site_builder["Static Site Builder<br/>documentation generator<br/>[build_site.py]"]
  node_validation_ci["Validation CI<br/>GitHub Actions workflow<br/>[validate.yml]"]
  node_pages_ci["Pages Deployment CI<br/>GitHub Actions workflow<br/>[pages.yml]"]
end

node_format_spec -->|"specifies"| node_bio_xsd
node_format_spec -->|"specifies"| node_bio_schematron
node_bio_xsd -.->|"generates compatibility variant"| node_libxml_schema
node_libxml_schema -->|"used for XSD checks"| node_schema_validator
node_bio_schematron -->|"applies rules"| node_package_validator
node_bio_xsd -->|"validates Bio resources"| node_package_validator
node_parameter_dossier -.->|"informs provenance and release policy"| node_package_validator
node_schema_validator -->|"runs within"| node_verify
node_package_validator -->|"runs within"| node_verify
node_machine_profile -->|"selects capabilities"| node_questionnaire
node_questionnaire -->|"supplies answers"| node_integrator
node_machine_profile -->|"supplies profile"| node_integrator
node_integrator -->|"emits conforming resources"| node_bio_xsd
node_integrator -->|"validates output"| node_package_validator
node_tomographic_example -->|"validated as reference"| node_package_validator
node_extrusion_example -->|"validated as reference"| node_package_validator
node_extrusion_toolpath -->|"contained in"| node_extrusion_example
node_tomographic_example -->|"inspects locally"| node_viewer
node_extrusion_example -->|"inspects locally"| node_viewer
node_dossier -->|"contains supporting records"| node_parameter_dossier
node_regulatory_review -.->|"reviews factual mapping"| node_dossier
node_dataset_sheet -.->|"scopes dataset collection"| node_dossier
node_verify -->|"executed by"| node_validation_ci
node_site_builder -->|"builds before deployment"| node_pages_ci
node_validation_ci -.->|"quality gate"| node_pages_ci

click node_bio_xsd "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/bio.xsd"
click node_bio_schematron "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/bio.sch"
click node_format_spec "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/3MF%20Bio%20Extension.md"
click node_libxml_schema "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/bio.libxml.xsd"
click node_schema_validator "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/validate_schema.py"
click node_package_validator "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/validate_bio.py"
click node_verify "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/verify.py"
click node_questionnaire "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/tools/questionnaire.py"
click node_machine_profile "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/tools/machine_profiles/brinter.json"
click node_integrator "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/tools/integrate.py"
click node_viewer "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/tools/viewer.html"
click node_extrusion_toolpath "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/examples-extrusion/bio/toolpath/extrusion.gcode"
click node_parameter_dossier "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/dossier/Parameter-Dossier.md"
click node_regulatory_review "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/review/REGULATORY-REVIEW.md"
click node_dataset_sheet "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/review/DATASET-SHEET.md"
click node_site_builder "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/site/build_site.py"
click node_validation_ci "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/.github/workflows/validate.yml"
click node_pages_ci "https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/.github/workflows/pages.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bio_xsd,node_bio_schematron,node_format_spec toneBlue
class node_libxml_schema,node_schema_validator,node_package_validator,node_verify toneAmber
class node_questionnaire,node_machine_profile,node_integrator,node_viewer toneMint
class node_tomographic_example,node_extrusion_example,node_extrusion_toolpath toneRose
class node_parameter_dossier,node_dossier,node_regulatory_review,node_dataset_sheet toneIndigo
class node_site_builder,node_validation_ci,node_pages_ci toneTeal
```

## Components

### Canonical Format

- [Bio XML Schema](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/bio.xsd): normative schema · Defines typed Bio resources in 3MF resources. · `spec/bio.xsd`
- [Bio Schematron](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/bio.sch): rule set · Portable intra-document semantic constraints. · `spec/bio.sch`
- [Extension Specification](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/3MF%20Bio%20Extension.md): format documentation · `spec/3MF Bio Extension.md`

### Validation

- [libxml Compatibility Schema](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/bio.libxml.xsd): generated schema · libxml2/lxml-compatible XSD variant. · `spec/bio.libxml.xsd`
- [Schema Validator](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/validate_schema.py): XSD validator · Checks XML structure and declared schema rules. · `spec/validate_schema.py`
- [Package Validator](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/spec/validate_bio.py): package-aware validator · Checks OPC relationships, cross-part policy, bibliography, and bounds. · `spec/validate_bio.py`
- [Repository Verification](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/verify.py): validation entry point · Runs repository-level verification and conformance checks. · `verify.py`

### Authoring & Inspection

- [Questionnaire Generator](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/tools/questionnaire.py): authoring tool · Generates or fills package input responses. · `tools/questionnaire.py`
- [Brinter Machine Profile](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/tools/machine_profiles/brinter.json): machine capability data · `tools/machine_profiles/brinter.json`
- [3MF Integrator](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/tools/integrate.py): package generator · Combines geometry, profile, and questionnaire answers into a validating package. · `tools/integrate.py`
- [Local Package Viewer](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/tools/viewer.html): browser inspector · Browser-only inspection of run sheets, constraints, records, and geometry. · `tools/viewer.html`

### Reference Packages

- **Tomographic Reference Package**: reference package · Executable volumetric-build reference data.
- **Extrusion Reference Package**: reference package · Multi-head deposition package with biological and operational records.
- [Extrusion Toolpath](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/examples-extrusion/bio/toolpath/extrusion.gcode): G-code · `examples-extrusion/bio/toolpath/extrusion.gcode`

### Evidence & Review

- [Parameter Dossier](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/dossier/Parameter-Dossier.md): provenance policy · Documents sources, calibration, unknowns, and release semantics. · `dossier/Parameter-Dossier.md`
- **Evidence Dossiers**: supporting records · Holds sources, regulatory mapping, bibliography, and fact checks.
- [Regulatory Review](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/review/REGULATORY-REVIEW.md): external review scope · `review/REGULATORY-REVIEW.md`
- [Dataset Sheet](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/review/DATASET-SHEET.md): dataset review scope · `review/DATASET-SHEET.md`

### Publication

- [Static Site Builder](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/site/build_site.py): documentation generator · Builds documentation and namespace site from Markdown. · `site/build_site.py`
- [Validation CI](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/.github/workflows/validate.yml): GitHub Actions workflow · `.github/workflows/validate.yml`
- [Pages Deployment CI](https://github.com/brinter-am-technologies-oy/3mf-bio/blob/main/.github/workflows/pages.yml): GitHub Actions workflow · `.github/workflows/pages.yml`

## Connections

- Extension Specification → Bio XML Schema: specifies
- Extension Specification → Bio Schematron: specifies
- Bio XML Schema → libxml Compatibility Schema: generates compatibility variant
- libxml Compatibility Schema → Schema Validator: used for XSD checks
- Bio Schematron → Package Validator: applies rules
- Bio XML Schema → Package Validator: validates Bio resources
- Parameter Dossier → Package Validator: informs provenance and release policy
- Schema Validator → Repository Verification: runs within
- Package Validator → Repository Verification: runs within
- Brinter Machine Profile → Questionnaire Generator: selects capabilities
- Questionnaire Generator → 3MF Integrator: supplies answers
- Brinter Machine Profile → 3MF Integrator: supplies profile
- 3MF Integrator → Bio XML Schema: emits conforming resources
- 3MF Integrator → Package Validator: validates output
- Tomographic Reference Package → Package Validator: validated as reference
- Extrusion Reference Package → Package Validator: validated as reference
- Extrusion Toolpath → Extrusion Reference Package: contained in
- Tomographic Reference Package → Local Package Viewer: inspects locally
- Extrusion Reference Package → Local Package Viewer: inspects locally
- Evidence Dossiers → Parameter Dossier: contains supporting records
- Regulatory Review → Evidence Dossiers: reviews factual mapping
- Dataset Sheet → Evidence Dossiers: scopes dataset collection
- Repository Verification → Validation CI: executed by
- Static Site Builder → Pages Deployment CI: builds before deployment
- Validation CI → Pages Deployment CI: quality gate