Architecture · Docs

This page explains how DevSnips' subsystems relate, which surfaces are canonical and which are derived, and how data flows between them. It is a map; the linked pages carry the detail.

Subsystems

                           DevSnips repository
                                   │
        ┌────────────┬────────────┼─────────────┬──────────────┐
        │            │            │             │              │
     library/      cli/       agents/        scripts/    integrations/
        │            │            │             │              │
    Canonical     Distribution  Agent layer   Tooling      MCP server
    UI resources  (npm package) (skill + docs (validators, (read-only)
    + metadata                  + indexes)    generators,
                                              QA harnesses)

Subsystem	Responsibility	Direction of dependency
`library/`	Canonical UI resources. The only place resource content lives.	Depends on nothing.
`scripts/`	Reads `library/` and produces every derived artifact; validates consistency.	Reads `library/`; writes generated artifacts.
`snippets-index.json`	The machine-readable registry. Derived from `library/`, consumed by everything else.	Generated; never edited.
`cli/`	Installs resources into user projects. Self-contained npm package (`devsnips`).	Reads the remote registry over HTTPS; ignores the local `library/` tree.
`agents/`	The skill (consume-side operational contract) and repository-side agent docs + generated per-type indexes.	Documents and indexes the system; never changes resource behavior.
`integrations/`	Integrations that consume the library. Currently the read-only MCP server (`integrations/mcp/`) that exposes the library to AI agents over stdio.	Reads the registry and `library/` files; read-only, never writes resources.
`docs/`	Contributor and platform documentation (this tree).	Describes the system; not a runtime dependency of anything.

The canonical / generated split

The single most important architectural rule:

Canonical: the filesystem under library/ and each resource's metadata.json.
Generated — never hand-edit: snippets-index.json, agents/resources/indexes/*.json.

Everything an agent or integrator queries — the registry, the per-type indexes — is a deterministic projection of library/. Two runs of the index generator over the same repository state produce identical output (the only intentional exception is the registry's lastUpdated date).

Never quote inventory counts from documentation. Read them from the current snippets-index.json.

Data flow

 library/**                     canonical files authored by contributors
     │
     │  scripts/tooling/indexing/rebuild_index.py
     │  (scans disk, preserves curated fields, cross-validates, refuses to write on mismatch)
     ▼
 snippets-index.json            machine-readable registry (tech-first paths)
     │
     ├──▶ scripts/tooling/indexing/build_resource_indexes.py
     │        per-type indexes: agents/resources/indexes/{components,sections,templates}-index.json
     │        (each variant carries id + install command)
     │
     ├──▶ scripts/tooling/validators/validate.py
     │        cross-checks registry ↔ disk in both directions
     │
     ├──▶ cli/src/registry/resolver.js
     │        fetches the registry from GitHub main; resolves `add <path>`
     │
     └──▶ integrations/mcp  (devsnips-mcp)
              reads the registry + library/<path>/<file>; serves read-only tools over stdio

One thing to note in this flow: the CLI and the MCP both read the published registry, not a local checkout's library/ tree (unless the MCP is explicitly pointed at one). A resource that exists on disk but is not in the published registry cannot be installed or served.

How a single resource flows through the system

A contributor creates library/Tailwind/Components/Buttons/some-variant/ with code.html, preview.html, metadata.json, README.md — see Resource structure.
The index generator scans it, builds its files manifest from what is actually on disk, and writes a variant record into snippets-index.json under family Buttons (tech Tailwind CSS, type component).
The specialized component index gains an entry whose id is the registry path and whose install field carries the exact CLI command.
validate.py confirms registry↔disk agreement, metadata validity, and architecture rules.
A consumer agent fetches the registry, filters on tech/type/tags, resolves the path, and runs npx devsnips add Tailwind/Components/Buttons/some-variant.
The CLI re-resolves against the remote registry, downloads the source files (plus README.md/AGENTS.md when present; never metadata.json/preview.html), writes them under ./devsnips/tailwind/components/buttons/some-variant/ in the user's project, and records the install in devsnips/config.json.

The three context layers

DevSnips involves three distinct AGENTS.md-style context files. They are not a hierarchy and do not override each other; each has a distinct scope:

File	Scope	Owner
`AGENTS.md` (repository root)	Working on the DevSnips repository: routing table into deep agent docs, safety rules, QA expectations.	Maintainers.
`<template>/AGENTS.md` (resource-level)	Working with one specific template: its structure, pages, and constraints. Required for every template, enforced by validators.	Contributors; validated.
`devsnips/AGENTS.md` (in a user project)	Working with installed DevSnips resources inside the user's project: adaptation rules and quality checks. Created once by the CLI, then user-owned.	The CLI creates it; the user owns it afterward.

See AGENTS.md context files for the full contract of each.

Boundaries

library/ is content. No tooling lives there (only token docs and gallery pages).
scripts/ is tooling. No resource content lives there.
cli/ is distribution. It is a self-contained npm package and must not depend on repository-relative paths.
integrations/ is integrations. integrations/mcp/ is read-only and shares the CLI's path conventions and installability rules, but is a separate process with no runtime dependency on the CLI.
CI (.github/workflows/ci.yml) runs the static gates on every push and pull request; the browser QA layers run manually. The process artifact is the pull-request template (.github/PULL_REQUEST_TEMPLATE.md), which requires reporting the validation commands run.

Where to go next

What is DevSnips — the conceptual model.
Philosophy — the reasoning behind this layout.
Resource model — types, families, variants, addressing.
Machine-readable overview — every queryable surface.
MCP — the read-only integration that exposes the library to agents.

Go deeper

This page is the human-facing architecture map. The implementation-anchored reference (top-level ownership map, the source-of-truth hierarchy, and the known-stale-reference ledger) is maintained for agents in agents/resources/architecture.md.