# mazinmarji/nornyx architecture

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

- Interactive diagram: https://gitdiagram.com/mazinmarji/nornyx
- Repository: https://github.com/mazinmarji/nornyx

## Overview

Nornyx is a vendor-neutral governance contract language and runtime for AI software delivery. The main workflow is to author or scaffold a `.nyx` contract, parse and check its governed inputs, generate control artifacts, and use revision-bound authorization and evidence validation where needed. Drift, workspace checks, context building, and package scanning provide additional assurance branches. Paths and links reflect the README, tree, and sampled source; several feature internals were not sampled, so their wiring is shown only where documented.

Main entry points: [`nornyx/cli.py`](https://github.com/mazinmarji/nornyx/blob/main/nornyx/cli.py) (CLI), [`nornyx/agentic/authz.py`](https://github.com/mazinmarji/nornyx/blob/main/nornyx/agentic/authz.py) (Authorization engine), [`nornyx/governance/versions.py`](https://github.com/mazinmarji/nornyx/blob/main/nornyx/governance/versions.py) (Locks and revisions), [`nornyx/parser.py`](https://github.com/mazinmarji/nornyx/blob/main/nornyx/parser.py) (Contract parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contract["Contract processing"]
  node_parser["Contract parser<br/>[parser.py]"]
  node_contract_model["Contract model<br/>[schema_model.py]"]
  node_checker["Contract checker<br/>[checker.py]"]
  node_profiles["Profiles<br/>[profiles.py]"]
end

subgraph group_artifacts["Control artifacts"]
  node_generator["Artifact generator<br/>[generator.py]"]
  node_control_artifacts["Tool control files"]
  node_context_builder["Context builder<br/>[context_builder.py]"]
  node_context_pack["Provenance context pack"]
end

subgraph group_revision["Revision governance"]
  node_governance_runtime["Governance runtime<br/>[runtime.py]"]
  node_lock_versions["Locks and revisions<br/>[versions.py]"]
end

subgraph group_runtime["Authorization runtime"]
  node_authz["Authorization engine<br/>[authz.py]"]
  node_authzen["AuthZEN mapping<br/>[authzen.py]"]
  node_evidence_validation["Evidence validation"]
  node_evidence_recorder["Evidence recorder<br/>[authz.py]"]
end

subgraph group_assurance["Assurance tools"]
  node_drift["Artifact drift checks"]
  node_workspace["Workspace checks<br/>[workspace.py]"]
  node_package_scanner["Governed package scanner<br/>[package_scanner.py]"]
  node_governed_package["Package inventory"]
end

node_engineer(("Project engineer"))
node_cli["CLI<br/>[cli.py]"]
node_external_pdp["External policy engine"]
node_pep_runtime["External PEPs and runtimes"]
node_runtime_events["Runtime-event evidence"]

node_engineer -->|"invokes"| node_cli
node_cli -->|"loads contract"| node_parser
node_parser -->|"produces model"| node_contract_model
node_cli -->|"checks contract"| node_checker
node_checker -->|"validates"| node_contract_model
node_cli -->|"scaffolds from"| node_profiles
node_cli -->|"generates artifacts"| node_generator
node_generator -->|"writes"| node_control_artifacts
node_cli -->|"builds context"| node_context_builder
node_context_builder -->|"produces"| node_context_pack
node_cli -->|"resolves governance"| node_governance_runtime
node_governance_runtime -->|"binds revision"| node_lock_versions
node_authz -->|"verifies lock"| node_lock_versions
node_authzen -->|"maps requests"| node_authz
node_external_pdp -.->|"returns decision"| node_pep_runtime
node_authz -.->|"supplies decision"| node_pep_runtime
node_pep_runtime -->|"supplies evidence"| node_evidence_validation
node_evidence_validation -->|"checks revision"| node_lock_versions
node_evidence_recorder -->|"records intents"| node_runtime_events
node_cli -->|"checks generated drift"| node_drift
node_cli -->|"checks workspace"| node_workspace
node_cli -->|"scans package inputs"| node_package_scanner
node_package_scanner -->|"builds inventory"| node_governed_package

click node_cli "https://github.com/mazinmarji/nornyx/blob/main/nornyx/cli.py"
click node_parser "https://github.com/mazinmarji/nornyx/blob/main/nornyx/parser.py"
click node_contract_model "https://github.com/mazinmarji/nornyx/blob/main/nornyx/schema_model.py"
click node_checker "https://github.com/mazinmarji/nornyx/blob/main/nornyx/checker.py"
click node_profiles "https://github.com/mazinmarji/nornyx/blob/main/nornyx/profiles.py"
click node_generator "https://github.com/mazinmarji/nornyx/blob/main/nornyx/generator.py"
click node_context_builder "https://github.com/mazinmarji/nornyx/blob/main/nornyx/context_builder.py"
click node_governance_runtime "https://github.com/mazinmarji/nornyx/blob/main/nornyx/governance/runtime.py"
click node_lock_versions "https://github.com/mazinmarji/nornyx/blob/main/nornyx/governance/versions.py"
click node_authz "https://github.com/mazinmarji/nornyx/blob/main/nornyx/agentic/authz.py"
click node_authzen "https://github.com/mazinmarji/nornyx/blob/main/nornyx/agentic/authzen.py"
click node_evidence_validation "https://github.com/mazinmarji/nornyx/blob/main/nornyx/governance/evidence_validation.py"
click node_evidence_recorder "https://github.com/mazinmarji/nornyx/blob/main/nornyx/agentic/authz.py"
click node_drift "https://github.com/mazinmarji/nornyx/blob/main/nornyx/generation_drift.py"
click node_workspace "https://github.com/mazinmarji/nornyx/blob/main/nornyx/workspace.py"
click node_package_scanner "https://github.com/mazinmarji/nornyx/blob/main/nornyx/package_scanner.py"
click node_governed_package "https://github.com/mazinmarji/nornyx/blob/main/nornyx/governed_package.py"

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_parser,node_contract_model,node_checker,node_profiles toneBlue
class node_generator,node_control_artifacts,node_context_builder,node_context_pack toneAmber
class node_governance_runtime,node_lock_versions toneMint
class node_authz,node_authzen,node_evidence_validation,node_evidence_recorder toneRose
class node_drift,node_workspace,node_package_scanner,node_governed_package,node_engineer,node_external_pdp,node_pep_runtime,node_runtime_events toneIndigo
class node_cli toneTeal
```

## Components

### Contract processing

- [Contract parser](https://github.com/mazinmarji/nornyx/blob/main/nornyx/parser.py): `nornyx/parser.py`
- [Contract model](https://github.com/mazinmarji/nornyx/blob/main/nornyx/schema_model.py): `nornyx/schema_model.py`
- [Contract checker](https://github.com/mazinmarji/nornyx/blob/main/nornyx/checker.py): `nornyx/checker.py`
- [Profiles](https://github.com/mazinmarji/nornyx/blob/main/nornyx/profiles.py): `nornyx/profiles.py`

### Control artifacts

- [Artifact generator](https://github.com/mazinmarji/nornyx/blob/main/nornyx/generator.py): `nornyx/generator.py`
- **Tool control files**
- [Context builder](https://github.com/mazinmarji/nornyx/blob/main/nornyx/context_builder.py): `nornyx/context_builder.py`
- **Provenance context pack**

### Revision governance

- [Governance runtime](https://github.com/mazinmarji/nornyx/blob/main/nornyx/governance/runtime.py): `nornyx/governance/runtime.py`
- [Locks and revisions](https://github.com/mazinmarji/nornyx/blob/main/nornyx/governance/versions.py): `nornyx/governance/versions.py`

### Authorization runtime

- [Authorization engine](https://github.com/mazinmarji/nornyx/blob/main/nornyx/agentic/authz.py): `nornyx/agentic/authz.py`
- [AuthZEN mapping](https://github.com/mazinmarji/nornyx/blob/main/nornyx/agentic/authzen.py): `nornyx/agentic/authzen.py`
- [Evidence validation](https://github.com/mazinmarji/nornyx/blob/main/nornyx/governance/evidence_validation.py): `nornyx/governance/evidence_validation.py`
- [Evidence recorder](https://github.com/mazinmarji/nornyx/blob/main/nornyx/agentic/authz.py): `nornyx/agentic/authz.py`

### Assurance tools

- [Artifact drift checks](https://github.com/mazinmarji/nornyx/blob/main/nornyx/generation_drift.py): `nornyx/generation_drift.py`
- [Workspace checks](https://github.com/mazinmarji/nornyx/blob/main/nornyx/workspace.py): `nornyx/workspace.py`
- [Governed package scanner](https://github.com/mazinmarji/nornyx/blob/main/nornyx/package_scanner.py): `nornyx/package_scanner.py`
- [Package inventory](https://github.com/mazinmarji/nornyx/blob/main/nornyx/governed_package.py): `nornyx/governed_package.py`

### Other components

- **Project engineer**
- [CLI](https://github.com/mazinmarji/nornyx/blob/main/nornyx/cli.py): `nornyx/cli.py`
- **External policy engine**
- **External PEPs and runtimes**
- **Runtime-event evidence**

## Connections

- Project engineer → CLI: invokes
- CLI → Contract parser: loads contract
- Contract parser → Contract model: produces model
- CLI → Contract checker: checks contract
- Contract checker → Contract model: validates
- CLI → Profiles: scaffolds from
- CLI → Artifact generator: generates artifacts
- Artifact generator → Tool control files: writes
- CLI → Context builder: builds context
- Context builder → Provenance context pack: produces
- CLI → Governance runtime: resolves governance
- Governance runtime → Locks and revisions: binds revision
- Authorization engine → Locks and revisions: verifies lock
- AuthZEN mapping → Authorization engine: maps requests
- External policy engine → External PEPs and runtimes: returns decision
- Authorization engine → External PEPs and runtimes: supplies decision
- External PEPs and runtimes → Evidence validation: supplies evidence
- Evidence validation → Locks and revisions: checks revision
- Evidence recorder → Runtime-event evidence: records intents
- CLI → Artifact drift checks: checks generated drift
- CLI → Workspace checks: checks workspace
- CLI → Governed package scanner: scans package inputs
- Governed package scanner → Package inventory: builds inventory