# gemaraproj/gemara architecture

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

- Interactive diagram: https://gitdiagram.com/gemaraproj/gemara
- Repository: https://github.com/gemaraproj/gemara

## Overview

Gemara is a CUE-based model for representing governance, risk, and security data, with a Go CLI that projects schemas to OpenAPI and checks schema changes for backward compatibility. The main user workflow is to run the CLI against the CUE package, generate and normalize an OpenAPI document, then optionally write a source manifest. The CUE files define the model’s catalogs, policies, mappings, and logs. The excerpts show CLI orchestration and projection internals; relationships among individual schema definitions are not established, so they are shown without invented links.

Main entry points: [`cmd/internal/cmd/projection/cmd.go`](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/cmd.go) (Projection command), [`cmd/internal/cmd/projection/converter.go`](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/converter.go) (Converter lifecycle), [`cmd/internal/cmd/diff/cmd.go`](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/diff/cmd.go) (Breaking check command), [`cmd/internal/cmd/root.go`](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/root.go) (Command root)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["CUE Data Model"]
  node_schemas["CUE package"]
  node_audit["Audit log<br/>[auditlog.cue]"]
  node_capability["Capability catalog"]
  node_collections["Collections<br/>[collections.cue]"]
  node_control["Control catalog<br/>[controlcatalog.cue]"]
  node_enforcement["Enforcement log<br/>[enforcementlog.cue]"]
  node_entities["Entities<br/>[entities.cue]"]
  node_evaluation["Evaluation log<br/>[evaluationlog.cue]"]
  node_guidance["Guidance catalog"]
  node_lexicon["Lexicon<br/>[lexicon.cue]"]
  node_mappinginline["Inline mapping<br/>[mapping_inline.cue]"]
  node_mappingdoc["Mapping document"]
  node_metadata["Metadata<br/>[metadata.cue]"]
  node_policy["Policy<br/>[policy.cue]"]
  node_principle["Principle catalog"]
  node_risk["Risk catalog<br/>[riskcatalog.cue]"]
  node_threat["Threat catalog<br/>[threatcatalog.cue]"]
  node_vector["Vector catalog<br/>[vectorcatalog.cue]"]
end

subgraph group_projection["OpenAPI Projection"]
  node_projectioncmd["Projection command<br/>[cmd.go]"]
  node_converter["Converter lifecycle<br/>[converter.go]"]
  node_preparation["CUE preparation<br/>[prep.go]"]
  node_annotations["Schema annotations<br/>[annotate.go]"]
  node_generation["OpenAPI generation<br/>[generate.go]"]
  node_postprocess["OpenAPI normalization<br/>[post.go]"]
  node_options["Projection options<br/>[options.go]"]
end

subgraph group_compatibility["Compatibility Checks"]
  node_breakingcmd["Breaking check command<br/>[cmd.go]"]
  node_breaking["Compatibility analysis<br/>[breaking.go]"]
end

subgraph group_cli["CLI Runtime"]
  node_entry["Program entry<br/>[main.go]"]
  node_commands["Command root<br/>[root.go]"]
end

node_user(("CLI user"))

node_user -->|"runs"| node_entry
node_entry -->|"executes"| node_commands
node_commands -->|"registers"| node_projectioncmd
node_commands -->|"registers"| node_breakingcmd
node_projectioncmd -->|"configures and runs"| node_converter
node_converter -->|"generates document"| node_generation
node_projectioncmd -->|"prepares package"| node_preparation
node_projectioncmd -->|"normalizes output"| node_postprocess
node_converter -.->|"postprocesses"| node_postprocess
node_converter -.->|"uses metadata"| node_annotations
node_projectioncmd -->|"sets options"| node_options
node_breakingcmd -->|"generates candidate"| node_converter
node_breakingcmd -.->|"checks changes"| node_breaking

click node_audit "https://github.com/gemaraproj/gemara/blob/main/auditlog.cue"
click node_capability "https://github.com/gemaraproj/gemara/blob/main/capabilitycatalog.cue"
click node_collections "https://github.com/gemaraproj/gemara/blob/main/collections.cue"
click node_control "https://github.com/gemaraproj/gemara/blob/main/controlcatalog.cue"
click node_enforcement "https://github.com/gemaraproj/gemara/blob/main/enforcementlog.cue"
click node_entities "https://github.com/gemaraproj/gemara/blob/main/entities.cue"
click node_evaluation "https://github.com/gemaraproj/gemara/blob/main/evaluationlog.cue"
click node_guidance "https://github.com/gemaraproj/gemara/blob/main/guidancecatalog.cue"
click node_lexicon "https://github.com/gemaraproj/gemara/blob/main/lexicon.cue"
click node_mappinginline "https://github.com/gemaraproj/gemara/blob/main/mapping_inline.cue"
click node_mappingdoc "https://github.com/gemaraproj/gemara/blob/main/mappingdocument.cue"
click node_metadata "https://github.com/gemaraproj/gemara/blob/main/metadata.cue"
click node_policy "https://github.com/gemaraproj/gemara/blob/main/policy.cue"
click node_principle "https://github.com/gemaraproj/gemara/blob/main/principlecatalog.cue"
click node_risk "https://github.com/gemaraproj/gemara/blob/main/riskcatalog.cue"
click node_threat "https://github.com/gemaraproj/gemara/blob/main/threatcatalog.cue"
click node_vector "https://github.com/gemaraproj/gemara/blob/main/vectorcatalog.cue"
click node_entry "https://github.com/gemaraproj/gemara/blob/main/cmd/main.go"
click node_commands "https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/root.go"
click node_projectioncmd "https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/cmd.go"
click node_converter "https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/converter.go"
click node_preparation "https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/prep.go"
click node_annotations "https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/annotate.go"
click node_generation "https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/generate.go"
click node_postprocess "https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/post.go"
click node_options "https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/options.go"
click node_breakingcmd "https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/diff/cmd.go"
click node_breaking "https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/diff/breaking.go"

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_schemas,node_audit,node_capability,node_collections,node_control,node_enforcement,node_entities,node_evaluation,node_guidance,node_lexicon,node_mappinginline,node_mappingdoc,node_metadata,node_policy,node_principle,node_risk,node_threat,node_vector,node_user toneBlue
class node_projectioncmd,node_converter,node_preparation,node_annotations,node_generation,node_postprocess,node_options toneAmber
class node_breakingcmd,node_breaking toneMint
class node_entry,node_commands toneRose
```

## Components

### CUE Data Model

- **CUE package**
- [Audit log](https://github.com/gemaraproj/gemara/blob/main/auditlog.cue): `auditlog.cue`
- [Capability catalog](https://github.com/gemaraproj/gemara/blob/main/capabilitycatalog.cue): `capabilitycatalog.cue`
- [Collections](https://github.com/gemaraproj/gemara/blob/main/collections.cue): `collections.cue`
- [Control catalog](https://github.com/gemaraproj/gemara/blob/main/controlcatalog.cue): `controlcatalog.cue`
- [Enforcement log](https://github.com/gemaraproj/gemara/blob/main/enforcementlog.cue): `enforcementlog.cue`
- [Entities](https://github.com/gemaraproj/gemara/blob/main/entities.cue): `entities.cue`
- [Evaluation log](https://github.com/gemaraproj/gemara/blob/main/evaluationlog.cue): `evaluationlog.cue`
- [Guidance catalog](https://github.com/gemaraproj/gemara/blob/main/guidancecatalog.cue): `guidancecatalog.cue`
- [Lexicon](https://github.com/gemaraproj/gemara/blob/main/lexicon.cue): `lexicon.cue`
- [Inline mapping](https://github.com/gemaraproj/gemara/blob/main/mapping_inline.cue): `mapping_inline.cue`
- [Mapping document](https://github.com/gemaraproj/gemara/blob/main/mappingdocument.cue): `mappingdocument.cue`
- [Metadata](https://github.com/gemaraproj/gemara/blob/main/metadata.cue): `metadata.cue`
- [Policy](https://github.com/gemaraproj/gemara/blob/main/policy.cue): `policy.cue`
- [Principle catalog](https://github.com/gemaraproj/gemara/blob/main/principlecatalog.cue): `principlecatalog.cue`
- [Risk catalog](https://github.com/gemaraproj/gemara/blob/main/riskcatalog.cue): `riskcatalog.cue`
- [Threat catalog](https://github.com/gemaraproj/gemara/blob/main/threatcatalog.cue): `threatcatalog.cue`
- [Vector catalog](https://github.com/gemaraproj/gemara/blob/main/vectorcatalog.cue): `vectorcatalog.cue`

### OpenAPI Projection

- [Projection command](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/cmd.go): `cmd/internal/cmd/projection/cmd.go`
- [Converter lifecycle](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/converter.go): `cmd/internal/cmd/projection/converter.go`
- [CUE preparation](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/prep.go): `cmd/internal/cmd/projection/prep.go`
- [Schema annotations](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/annotate.go): `cmd/internal/cmd/projection/annotate.go`
- [OpenAPI generation](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/generate.go): `cmd/internal/cmd/projection/generate.go`
- [OpenAPI normalization](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/post.go): `cmd/internal/cmd/projection/post.go`
- [Projection options](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/projection/options.go): `cmd/internal/cmd/projection/options.go`

### Compatibility Checks

- [Breaking check command](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/diff/cmd.go): `cmd/internal/cmd/diff/cmd.go`
- [Compatibility analysis](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/diff/breaking.go): `cmd/internal/cmd/diff/breaking.go`

### CLI Runtime

- [Program entry](https://github.com/gemaraproj/gemara/blob/main/cmd/main.go): `cmd/main.go`
- [Command root](https://github.com/gemaraproj/gemara/blob/main/cmd/internal/cmd/root.go): `cmd/internal/cmd/root.go`

### Other components

- **CLI user**

## Connections

- CLI user → Program entry: runs (evidence: `README.md`)
- Program entry → Command root: executes (evidence: `cmd/main.go`)
- Command root → Projection command: registers (evidence: `cmd/internal/cmd/root.go`)
- Command root → Breaking check command: registers (evidence: `cmd/internal/cmd/root.go`)
- Projection command → Converter lifecycle: configures and runs (evidence: `cmd/internal/cmd/projection/cmd.go`)
- Converter lifecycle → OpenAPI generation: generates document (evidence: `cmd/internal/cmd/projection/converter.go`)
- Projection command → CUE preparation: prepares package (evidence: `cmd/internal/cmd/projection/cmd.go`)
- Projection command → OpenAPI normalization: normalizes output (evidence: `cmd/internal/cmd/projection/cmd.go`)
- Converter lifecycle → OpenAPI normalization: postprocesses
- Converter lifecycle → Schema annotations: uses metadata
- Projection command → Projection options: sets options (evidence: `cmd/internal/cmd/projection/cmd.go`)
- Breaking check command → Converter lifecycle: generates candidate (evidence: `cmd/internal/cmd/diff/cmd.go`)
- Breaking check command → Compatibility analysis: checks changes
