# vortexpixelz/mcore-1 architecture

> Architecture diagram of the GitHub repository vortexpixelz/mcore-1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vortexpixelz/mcore-1
- Repository: https://github.com/vortexpixelz/mcore-1

## Overview

1. **What this repo is**
   - `mcore-py` is the reference Python implementation of the MCORE-1 specification.
   - The architecture is centered on a **core metrical/state model**, then layered with **algebra**, **validation**, **encodings**, **overlays**, and **renderers**.

2. **Source of truth and documentation boundary**
   - `docs/MCORE-1-v0.1-spec.pdf` is the formal specification.
   - `README.md` describes the intended conformance levels and is effectively the public architecture guide.
   - The notebooks and root-level scripts act as worked examples and experimental applications rather than the core library.

3. **Core domain model**
   - `src/mcore_py/model.py` defines the primary data structures: trits, weights, levels, prosodic units, constituents, and budgets.
   - `src/mcore_py/__init__.py` exposes the public API, so consumers can import the model and utility functions from one place.
   - This is the main boundary between “user data” and the rest of the system.

4. **Algebra and generation**
   - `src/mcore_py/algebra.py` contains the trit algebra and pattern enumeration logic.
   - This is where the repository’s central invariants live: ternary weights, addition/composition, and completion of partial structures into valid ones.
   - Generation flows from a budget or target weight into all admissible patterns.

5. **Validation pipeline**
   - `src/mcore_py/checker.py` verifies trees/constituents against algebraic constraints.
   - The checker is the analysis side of the system: it confirms conservation and well-formedness rather than generating candidates.
   - In architecture terms, it sits between the model and any serialization/rendering layer.

6. **Surface syntaxes and encodings**
   - `src/mcore_py/mss.py` handles the human-readable surface syntax.
   - `src/mcore_py/tme6.py` implements the compact 6-bit opcode encoding.
   - `src/mcore_py/base64tme.py` adds text-safe Base64 serialization on top of TME-6.
   - Data can therefore move from human notation to compact binary/text encodings and back.

7. **Traditional overlays as extension modules**
   - `src/mcore_py/overlays/` is the extension boundary for tradition-specific or domain-specific semantics.
   - `quantitative_metrics.py` appears to provide the primary prosody overlay; `quantum.py` and `stubs.py` suggest additional experimental or placeholder overlays.
   - These overlays adapt the same core algebra/model to different interpretation domains without changing the base representation.

8. **Rendering/output layer**
   - `src/mcore_py/renderers/terminal.py` and `token_stream.py` are presentation adapters.
   - They turn internal structures into terminal-friendly output or token streams, keeping display concerns out of the core checker/algebra code.
   - The README notes audio as a future renderer, so this layer is intended to be expandable.

9. **CLI as the integration hub**
   - `src/mcore_py/cli.py` is the main user-facing orchestration layer.
   - It connects parsing, checking, encoding/decoding, completion, and diagnostics into commands like `validate`, `complete`, `encode`, `decode`, `doctor`, `smoke`, and `notebook-smoke`.
   - For architecture diagrams, this is the entry point that binds the library subsystems into a runnable tool.

10. **Examples, notebooks, and experimental applications**
   - `notebooks/` and `S3_Cosmological_Crystallization_Analysis.ipynb` show interactive usage and domain exploration.
   - `s3_crystallization_analysis.py` and `S3_Winner_Subset_Characterization.py` are standalone analysis scripts, likely downstream consumers of the same model/checker ideas.
   - These are application/demo artifacts, not part of the core package boundary.

11. **Tests and quality gates**
   - `tests/test_mcore.py` and `tests/test_quantum_overlay.py` validate the core API and overlay behavior.
   - `tests/test_s3_analysis_scripts.py` covers the standalone analysis scripts.
   - The notebooks in `tests/` suggest some end-to-end or exploratory validation as part of the repo’s quality strategy.

12. **Packaging and delivery**
   - `pyproject.toml` defines the Python package and development workflow.
   - `.github/workflows/python-app.yml` provides CI automation, so the repo is built and tested in GitHub Actions.
   - There is no heavy runtime infrastructure here; the system is primarily a local Python library/CLI with documentation and notebooks around it.

Main entry points: [`src/mcore_py/model.py`](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/model.py) (Core model), [`src/mcore_py/cli.py`](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/cli.py) (CLI), [`tests`](https://github.com/vortexpixelz/mcore-1/tree/main/tests) (Tests), [`src/mcore_py/checker.py`](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/checker.py) (Checker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs"]
  node_spec["Spec PDF<br/>specification"]
  node_readme["README<br/>guide<br/>[README.md]"]
end

subgraph group_core["Core library"]
  node_model["Core model<br/>domain model<br/>[model.py]"]
  node_api["Public API<br/>package facade<br/>[__init__.py]"]
  node_algebra["Algebra<br/>[algebra.py]"]
  node_checker["Checker<br/>validation<br/>[checker.py]"]
  node_mss["MSS<br/>surface syntax<br/>[mss.py]"]
  node_tme6["TME-6<br/>opcode encoding<br/>[tme6.py]"]
  node_b64["Base64 TME<br/>text encoding<br/>[base64tme.py]"]
end

subgraph group_ext["Extensions"]
  node_overlays["Overlays<br/>extension boundary"]
  node_qmetrics["Metrics overlay<br/>prosody overlay"]
  node_quantum["Quantum overlay<br/>experimental overlay<br/>[quantum.py]"]
  node_renderers["Renderers<br/>presentation layer"]
end

subgraph group_apps["Apps"]
  node_cli["CLI<br/>orchestration<br/>[cli.py]"]
  node_notebooks["Notebooks<br/>exploration"]
  node_s3scripts["Analysis scripts<br/>standalone analysis"]
end

subgraph group_quality["Quality"]
  node_tests["Tests<br/>verification"]
  node_ci["CI workflow<br/>automation<br/>[python-app.yml]"]
end

node_readme -->|"documents"| node_spec
node_api -->|"exports"| node_model
node_api -->|"exports"| node_algebra
node_algebra -->|"operates on"| node_model
node_checker -->|"validates"| node_model
node_checker -->|"depends on"| node_algebra
node_mss -->|"parses"| node_model
node_tme6 -->|"serializes"| node_model
node_b64 -->|"wraps"| node_tme6
node_overlays -->|"extends"| node_model
node_qmetrics -->|"implements"| node_overlays
node_quantum -->|"implements"| node_overlays
node_renderers -->|"renders"| node_model
node_cli -->|"uses"| node_mss
node_cli -->|"uses"| node_checker
node_cli -->|"uses"| node_b64
node_cli -->|"uses"| node_overlays
node_cli -->|"uses"| node_renderers
node_notebooks -.->|"demonstrates"| node_cli
node_s3scripts -->|"analyzes"| node_model
node_tests -->|"covers"| node_checker
node_tests -->|"covers"| node_quantum
node_tests -->|"covers"| node_s3scripts
node_ci -->|"runs"| node_tests

click node_spec "https://github.com/vortexpixelz/mcore-1/blob/main/docs/MCORE-1-v0.1-spec.pdf"
click node_readme "https://github.com/vortexpixelz/mcore-1/blob/main/README.md"
click node_model "https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/model.py"
click node_api "https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/__init__.py"
click node_algebra "https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/algebra.py"
click node_checker "https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/checker.py"
click node_mss "https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/mss.py"
click node_tme6 "https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/tme6.py"
click node_b64 "https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/base64tme.py"
click node_overlays "https://github.com/vortexpixelz/mcore-1/tree/main/src/mcore_py/overlays"
click node_qmetrics "https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/overlays/quantitative_metrics.py"
click node_quantum "https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/overlays/quantum.py"
click node_renderers "https://github.com/vortexpixelz/mcore-1/tree/main/src/mcore_py/renderers"
click node_cli "https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/cli.py"
click node_notebooks "https://github.com/vortexpixelz/mcore-1/tree/main/notebooks"
click node_s3scripts "https://github.com/vortexpixelz/mcore-1/blob/main/s3_crystallization_analysis.py"
click node_tests "https://github.com/vortexpixelz/mcore-1/tree/main/tests"
click node_ci "https://github.com/vortexpixelz/mcore-1/blob/main/.github/workflows/python-app.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_spec,node_readme toneBlue
class node_model,node_api,node_algebra,node_checker,node_mss,node_tme6,node_b64 toneAmber
class node_overlays,node_qmetrics,node_quantum,node_renderers toneMint
class node_cli,node_notebooks,node_s3scripts toneRose
class node_tests,node_ci toneIndigo
```

## Components

### Docs

Specification and public architecture guidance

- [Spec PDF](https://github.com/vortexpixelz/mcore-1/blob/main/docs/MCORE-1-v0.1-spec.pdf): specification · Formal MCORE-1 reference document · `docs/MCORE-1-v0.1-spec.pdf`
- [README](https://github.com/vortexpixelz/mcore-1/blob/main/README.md): guide · Public conformance and architecture guide · `README.md`

### Core library

Primary package subsystems

- [Core model](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/model.py): domain model · Trits, weights, levels, constituents, and budgets · `src/mcore_py/model.py`
- [Public API](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/__init__.py): package facade · Top-level exports for consumers · `src/mcore_py/__init__.py`
- [Algebra](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/algebra.py): pattern algebra · Trit composition, invariants, and completion logic · `src/mcore_py/algebra.py`
- [Checker](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/checker.py): validation · Verifies structures against algebraic constraints · `src/mcore_py/checker.py`
- [MSS](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/mss.py): surface syntax · Human-readable input and output notation · `src/mcore_py/mss.py`
- [TME-6](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/tme6.py): opcode encoding · Compact 6-bit serialization format · `src/mcore_py/tme6.py`
- [Base64 TME](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/base64tme.py): text encoding · Text-safe wrapper around TME-6 · `src/mcore_py/base64tme.py`

### Extensions

Tradition-specific overlays and renderers

- [Overlays](https://github.com/vortexpixelz/mcore-1/tree/main/src/mcore_py/overlays): extension boundary · Domain-specific semantic layers built on the core model · `src/mcore_py/overlays`
- [Metrics overlay](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/overlays/quantitative_metrics.py): prosody overlay · Primary quantitative prosody adaptation · `src/mcore_py/overlays/quantitative_metrics.py`
- [Quantum overlay](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/overlays/quantum.py): experimental overlay · Alternate or experimental overlay semantics · `src/mcore_py/overlays/quantum.py`
- [Renderers](https://github.com/vortexpixelz/mcore-1/tree/main/src/mcore_py/renderers): presentation layer · Output adapters for terminal and token streams · `src/mcore_py/renderers`

### Apps

CLI, notebooks, and analysis scripts

- [CLI](https://github.com/vortexpixelz/mcore-1/blob/main/src/mcore_py/cli.py): orchestration · Command entry point for validate, complete, encode, decode, and diagnostics · `src/mcore_py/cli.py`
- [Notebooks](https://github.com/vortexpixelz/mcore-1/tree/main/notebooks): exploration · Interactive demos and worked examples · `notebooks`
- [Analysis scripts](https://github.com/vortexpixelz/mcore-1/blob/main/s3_crystallization_analysis.py): standalone analysis · Repo-level domain exploration and characterization scripts · `s3_crystallization_analysis.py`

### Quality

Tests and CI

- [Tests](https://github.com/vortexpixelz/mcore-1/tree/main/tests): verification · Unit, overlay, and script coverage · `tests`
- [CI workflow](https://github.com/vortexpixelz/mcore-1/blob/main/.github/workflows/python-app.yml): automation · GitHub Actions build and test pipeline · `.github/workflows/python-app.yml`

## Connections

- README → Spec PDF: documents · README points to the formal spec as source of truth
- Public API → Core model: exports · Package facade exposes the core domain model
- Public API → Algebra: exports · Package facade exposes algebra helpers
- Algebra → Core model: operates on · Algebra uses the core data structures
- Checker → Core model: validates · Checker consumes model objects and trees
- Checker → Algebra: depends on · Validation relies on the algebraic rules
- MSS → Core model: parses · Surface syntax maps to and from core structures
- TME-6 → Core model: serializes · Compact opcode encoding represents model structures
- Base64 TME → TME-6: wraps · Base64 text form is layered on TME-6
- Overlays → Core model: extends · Overlay modules adapt the shared core representation
- Metrics overlay → Overlays: implements · Primary overlay implementation
- Quantum overlay → Overlays: implements · Alternative overlay implementation
- Renderers → Core model: renders · Presentation adapters turn internal structures into output
- CLI → MSS: uses · CLI accepts or emits surface syntax
- CLI → Checker: uses · Validation commands route through the checker
- CLI → Base64 TME: uses · Encode/decode commands use text-safe serialization
- CLI → Overlays: uses · CLI can invoke overlay-aware behavior
- CLI → Renderers: uses · User-facing output is delegated to renderers
- Notebooks → CLI: demonstrates · Interactive examples exercise the package and commands
- Analysis scripts → Core model: analyzes · Standalone scripts use the same core abstractions
- Tests → Checker: covers · Tests verify validation behavior
- Tests → Quantum overlay: covers · Tests verify overlay behavior
- Tests → Analysis scripts: covers · Tests exercise analysis scripts
- CI workflow → Tests: runs · Workflow executes the test suite
