# quantifyearth/shark architecture

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

- Interactive diagram: https://gitdiagram.com/quantifyearth/shark
- Repository: https://github.com/quantifyearth/shark

## Overview

Shark builds Linux environments from specifications, runs commands in built environments, and also processes Markdown documents containing build, run, and publish blocks. Its documented template command expands frontmatter variables into generated documents. The graph shows those user-facing stages and the named runtime modules indicated by the tree; source excerpts were unavailable, so internal calls and unconfirmed wiring are omitted.

Main entry points: [`src/bin/main.ml`](https://github.com/quantifyearth/shark/blob/main/src/bin/main.ml) (Shark CLI), [`src/lib/block.ml`](https://github.com/quantifyearth/shark/blob/main/src/lib/block.ml) (Environment builder), [`src/lib/ast`](https://github.com/quantifyearth/shark/tree/main/src/lib/ast) (Build and run blocks), [`src/lib/run_block.ml`](https://github.com/quantifyearth/shark/blob/main/src/lib/run_block.ml) (Interactive shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli["Shark CLI<br/>[main.ml]"]
end

subgraph group_markdown["Markdown processing"]
  node_markdown_doc["Markdown document"]
  node_template["Template expansion<br/>[template.ml]"]
  node_generated_docs["Generated documents"]
  node_md_parser["Markdown conversion<br/>[md_to_ast.ml]"]
  node_markdown_blocks["Build and run blocks"]
  node_publish["Publish outputs<br/>[import.ml]"]
end

subgraph group_runtime["Build and execution"]
  node_spec["Build specification"]
  node_builder["Environment builder<br/>[block.ml]"]
  node_build_cache["Build cache<br/>[build_cache.ml]"]
  node_built_env[("Built environment")]
  node_shell["Interactive shell<br/>[run_block.ml]"]
  node_outputs[("Build outputs")]
end

subgraph group_configuration["Configuration and stores"]
  node_config["CLI configuration<br/>[config.ml]"]
  node_store[("Build store<br/>[zfs.md]")]
end

node_user(("User"))

node_user -->|"invokes"| node_cli
node_cli -->|"loads defaults"| node_config
node_cli -->|"requests build"| node_builder
node_spec -->|"defines build"| node_builder
node_builder -->|"uses cache"| node_build_cache
node_builder -->|"builds in"| node_store
node_builder -->|"produces"| node_built_env
node_cli -->|"requests shell"| node_shell
node_shell -->|"uses build"| node_store
node_user -->|"provides"| node_markdown_doc
node_cli -->|"runs template"| node_template
node_template -->|"expands variables"| node_markdown_doc
node_template -->|"generates"| node_generated_docs
node_cli -->|"processes Markdown"| node_md_parser
node_md_parser -->|"converts to"| node_markdown_blocks
node_markdown_blocks -->|"build blocks"| node_builder
node_markdown_blocks -->|"run blocks"| node_shell
node_shell -->|"tracks outputs"| node_outputs
node_markdown_blocks -->|"publish blocks"| node_publish
node_publish -->|"exports"| node_outputs

click node_cli "https://github.com/quantifyearth/shark/blob/main/src/bin/main.ml"
click node_config "https://github.com/quantifyearth/shark/blob/main/src/lib/config.ml"
click node_builder "https://github.com/quantifyearth/shark/blob/main/src/lib/block.ml"
click node_build_cache "https://github.com/quantifyearth/shark/blob/main/src/lib/build_cache.ml"
click node_store "https://github.com/quantifyearth/shark/blob/main/docs/zfs.md"
click node_shell "https://github.com/quantifyearth/shark/blob/main/src/lib/run_block.ml"
click node_template "https://github.com/quantifyearth/shark/blob/main/src/lib/template.ml"
click node_md_parser "https://github.com/quantifyearth/shark/blob/main/src/lib/md_to_ast.ml"
click node_markdown_blocks "https://github.com/quantifyearth/shark/tree/main/src/lib/ast"
click node_publish "https://github.com/quantifyearth/shark/blob/main/src/lib/import.ml"

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_cli,node_user toneBlue
class node_markdown_doc,node_template,node_generated_docs,node_md_parser,node_markdown_blocks,node_publish toneAmber
class node_spec,node_builder,node_build_cache,node_built_env,node_shell,node_outputs toneMint
class node_config,node_store toneRose
```

## Components

### CLI workflows

- [Shark CLI](https://github.com/quantifyearth/shark/blob/main/src/bin/main.ml): `src/bin/main.ml`

### Markdown processing

- **Markdown document**
- [Template expansion](https://github.com/quantifyearth/shark/blob/main/src/lib/template.ml): `src/lib/template.ml`
- **Generated documents**
- [Markdown conversion](https://github.com/quantifyearth/shark/blob/main/src/lib/md_to_ast.ml): `src/lib/md_to_ast.ml`
- [Build and run blocks](https://github.com/quantifyearth/shark/tree/main/src/lib/ast): `src/lib/ast`
- [Publish outputs](https://github.com/quantifyearth/shark/blob/main/src/lib/import.ml): `src/lib/import.ml`

### Build and execution

- **Build specification**
- [Environment builder](https://github.com/quantifyearth/shark/blob/main/src/lib/block.ml): `src/lib/block.ml`
- [Build cache](https://github.com/quantifyearth/shark/blob/main/src/lib/build_cache.ml): `src/lib/build_cache.ml`
- **Built environment**
- [Interactive shell](https://github.com/quantifyearth/shark/blob/main/src/lib/run_block.ml): `src/lib/run_block.ml`
- **Build outputs**

### Configuration and stores

- [CLI configuration](https://github.com/quantifyearth/shark/blob/main/src/lib/config.ml): `src/lib/config.ml`
- [Build store](https://github.com/quantifyearth/shark/blob/main/docs/zfs.md): `docs/zfs.md`

### Other components

- **User**

## Connections

- User → Shark CLI: invokes
- Shark CLI → CLI configuration: loads defaults
- Shark CLI → Environment builder: requests build
- Build specification → Environment builder: defines build
- Environment builder → Build cache: uses cache
- Environment builder → Build store: builds in
- Environment builder → Built environment: produces
- Shark CLI → Interactive shell: requests shell
- Interactive shell → Build store: uses build
- User → Markdown document: provides
- Shark CLI → Template expansion: runs template
- Template expansion → Markdown document: expands variables
- Template expansion → Generated documents: generates
- Shark CLI → Markdown conversion: processes Markdown
- Markdown conversion → Build and run blocks: converts to
- Build and run blocks → Environment builder: build blocks
- Build and run blocks → Interactive shell: run blocks
- Interactive shell → Build outputs: tracks outputs
- Build and run blocks → Publish outputs: publish blocks
- Publish outputs → Build outputs: exports