mif-docs Plugin — C4 Model

mif-docs Plugin — C4 Model

This model describes the mif-docs Claude Code plugin at three C4 levels of abstraction. Each diagram zooms in one level; the Code level (Level 4) is deliberately omitted. The element catalogs below each diagram are the durable record — the diagrams are one Mermaid rendering of those abstractions.

Level 1 — System Context

How the mif-docs plugin fits into the world: who uses it and which other systems it depends on.

C4Context
    title System Context diagram for the mif-docs plugin
    Person(author, "Author / Agent", "Writes documentation with a genre skill")
    System(mifdocs, "mif-docs Plugin", "Authors and validates MIF-conformant docs")
    System_Ext(host, "Claude Code Host", "Loads skills and runs the PostToolUse hook")
    System_Ext(schema, "mif-spec.dev Schema", "Canonical MIF JSON Schema")
    System_Ext(ontologies, "ontologies Repo", "Sibling MIF ontology source")
    System_Ext(market, "claude-code-plugins Marketplace", "Distributes and admits releases")
    Rel(author, mifdocs, "Authors documents using")
    Rel(host, mifdocs, "Loads skills and runs the guard of")
    Rel(mifdocs, schema, "Hydrates and validates against")
    Rel(mifdocs, ontologies, "Hydrates and vendors the ontology from")
    Rel(market, mifdocs, "Distributes; admits attested releases of")

Element	Kind	Responsibility
Author / Agent	person	Selects a genre skill and authors a document.
mif-docs Plugin	system (in scope)	Authors MIF docs and proves their conformance.
Claude Code Host	external system	Loads the plugin’s skills and runs its hook.
mif-spec.dev Schema	external system	Authoritative MIF JSON Schema for validation.
ontologies Repo	external system	Source of the MIF ontology vocabulary.
claude-code-plugins Marketplace	external system	Distributes the plugin; gates admission on attestation.

Level 2 — Container

Zooming into the mif-docs plugin to show its deployable/runnable containers and how they communicate.

C4Container
    title Container diagram for the mif-docs plugin
    Person(author, "Author / Agent", "Writes documentation with a genre skill")
    System_Ext(host, "Claude Code Host", "Loads skills and runs the hook")
    System_Ext(schema, "mif-spec.dev Schema", "Canonical MIF JSON Schema")
    Container_Boundary(c1, "mif-docs Plugin") {
        Container(skills, "Genre Skills", "Markdown skills", "38 genre + 7 substrate + planner authoring skills")
        Container(cli, "scripts / CLI", "Node.js (ESM)", "mif-validate, mif-convert, hydrate, validate")
        Container(guard, "hooks / guard", "Node.js (ESM)", "PostToolUse fail-closed write guard")
        ContainerDb(cache, "Schema Cache", "JSON + VENDOR.lock", "Hydrated canonical schema, version-locked")
    }
    Rel(author, skills, "Authors documents using")
    Rel(host, guard, "Fires on Write/Edit/MultiEdit via")
    Rel(guard, cli, "Runs mif-validate --level 1 through")
    Rel(cli, cache, "Loads the resolved schema from")
    Rel(cli, schema, "Hydrates the cache from", "HTTPS")

Element	Kind	Responsibility
Genre Skills	container	Author MIF documents, one skill per genre.
scripts / CLI	container	Deterministic projection, validation, and hydration tools.
hooks / guard	container	Blocks non-conformant genre writes at the L1 floor.
Schema Cache	container (datastore)	Holds the hydrated schema plus VENDOR.lock.
mif-spec.dev Schema	external system	Source the cache hydrates from over HTTPS.

Level 3 — Component

Zooming into the scripts / CLI container to show the components of mif-validate. The container name matches the Level 2 diagram exactly.

C4Component
    title Component diagram for the mif-docs plugin - mif-validate
    Container(guard, "hooks / guard", "Node.js", "Invokes the validator")
    ContainerDb(cache, "Schema Cache", "JSON + VENDOR.lock", "Hydrated canonical schema")
    Container_Boundary(cli, "scripts / CLI") {
        Component(parse, "Frontmatter Parser", "projection.mjs", "Parses YAML frontmatter and body")
        Component(project, "JSON-LD Projection", "projection.mjs", "Projects the doc to the canonical object")
        Component(ajv, "ajv Validator", "ajv + ajv-formats", "Validates JSON-LD against the schema")
        Component(level, "Level Overlay", "profiles/level-N.json", "Enforces the L1/L2/L3 required-field floor")
        Component(roundtrip, "Round-trip Oracle", "projection.mjs", "Checks markdown<->JSON-LD is lossless")
    }
    Rel(guard, parse, "Calls mif-validate, entering at")
    Rel(parse, project, "Hands frontmatter + body to")
    Rel(project, ajv, "Passes the JSON-LD object to")
    Rel(ajv, cache, "Loads the resolved schema from")
    Rel(project, level, "Checks the level floor with")
    Rel(project, roundtrip, "Verifies losslessness with")

Element	Kind	Responsibility
Frontmatter Parser	component	Splits the document into YAML frontmatter and body.
JSON-LD Projection	component	Maps frontmatter + body to the canonical JSON-LD object.
ajv Validator	component	Schema-checks the JSON-LD against the hydrated schema.
Level Overlay	component	Applies the required-field floor for the requested level.
Round-trip Oracle	component	Confirms the markdown↔JSON-LD round-trip loses nothing.

Notes

• Level 4 (Code) is intentionally omitted: it ages quickly and is better generated on demand from the IDE.
• Every relationship is labelled with intent and, where it matters, protocol.
• Technology tags sit on containers and components only — never on people or external systems.
• This C4 model is the kind of artifact the plugin’s arc42 architecture document embeds in its §3 Context and Scope (Level 1) and §5 Building Block View (Levels 2–3) sections — the relates-to relationship in the frontmatter records that genre-level link to arch-arc42-mif-docs.