prompts/docs/architecture.md

icon

icon
lucide/library

Architecture

Overview

The platform is implemented as a resource-first MCP system with an integrated static documentation surface. The same methodology content powers both MCP resources and the published docs site.

An MCP server is a runtime that exposes machine-readable resources and tools through stable interfaces so AI clients can discover and consume context consistently. Here, the server's role is intentionally narrow: publish canonical methodology documents as resources, keep discovery predictable through a catalog layer, and serve the same source material as pre-built static documentation.

The system is complete in three layers:

1. Canonical methodology is maintained in Markdown skill documents.
2. Catalog resources provide normalized discovery.
3. Zensical builds a static site from those same Markdown sources and the FastAPI app serves it in the FastMCP runtime process.

This architecture is anchored by three contracts:

1. Docs-first authored content contract under docs/ with strict per-skill ownership.
2. SKILL.md frontmatter contract with Anthropic fields plus x-personal-mcp metadata.
3. Canonical resource URI contract with break-and-replace policy for contract changes.

Detailed contract pages:

1. Content Contract
2. Frontmatter Contract
3. URI Contract

This architecture keeps authored content human-friendly while preserving machine-stable contracts.

Intent

The architecture is designed to satisfy three long-term requirements:

1. Methodology must be editable as markdown by humans.
2. Agents must consume stable, discoverable resource contracts, with a minimal read-only catalog tool fallback for constrained clients.
3. Public documentation must be pre-built static output served from the application runtime without a separate docs service.

System Model

Pattern Modules

Each skill encapsulates one methodology domain in a docs-owned directory:

1. docs/skills/<skill-id>/SKILL.md
2. docs/skills/<skill-id>/references/...

The skill document and references are the authored source of truth; runtime code indexes and serves these files without becoming a second authored source.

Each skill publishes resource families:

1. document

The document resource returns canonical Markdown, while clients can perform any downstream section extraction they need.

Catalog Module

The catalog is the canonical discovery layer and publishes normalized records for all modules. It may also expose a minimal set of read-only discovery tools that resolve back to the same canonical markdown content when a client chat surface does not expose MCP resource attachment.

Typical catalog resources:

1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}

Only canonical catalog resources are part of the runtime contract in this phase.

Registry Loader

The runtime composition includes a startup registry loader that reads packaged docs resources using importlib.resources.files(...) and Traversable APIs.

Loader responsibilities:

1. Parse SKILL.md frontmatter for each skill.
2. Validate schema and cross-field constraints before any resource registration.
3. Build an in-memory registry keyed by skill_id.
4. Fail fast for duplicate ids, missing markdown files, broken reference mappings, and invalid depends_on values.

Registry load failure is a startup error, not a partial runtime warning.

Content Sources

Content is authored in markdown under docs/ and managed as long-form reference material. Skill documents and companion references now live under docs/skills/, while project-authored pages remain alongside them in the docs tree. Resource handlers expose the same authored documents through stable resource URIs.

Static Docs Surface

Static docs are built directly from two markdown source streams:

1. Project-authored docs pages
2. Skill and reference markdown pages

The merged docs tree is built by Zensical into static files and served by the FastAPI app.

Data Flow

flowchart TD
    A[Authored Markdown] --> C[Resource Handlers]
    B[Pattern Metadata] --> D[Catalog Resources]
    A --> E[Zensical Static Build]
    E --> H[FastAPI Static Mount]
    H --> I[Served Docs Site]
    D --> I

Contracts

Metadata Contract

Each skill declares frontmatter in docs/skills/<skill-id>/SKILL.md.

For the full field-level contract, validation model, and FastMCP metadata mapping, see Frontmatter Contract.

Anthropic-facing required fields:

1. name
2. description

Repository indexing metadata is declared in x-personal-mcp:

1. id
2. version
3. tags
4. capabilities
5. depends_on
6. references map (ref id to relative path and optional metadata)

No metadata.yaml sidecar is part of the end-state contract.

URI Contract

Canonical resource URIs are:

For the full URI semantics, parameter validation rules, and compatibility policy, see URI Contract.

1. resource://skills/<skill_id>/document
2. resource://skills/<skill_id>/references/<ref_id>
3. resource://catalog/skills_index
4. resource://catalog/skills/{skill_id}
5. resource://docs/{path*}

Validation rules:

1. skill_id is lowercase kebab-case and must satisfy the stable skill id contract.
2. ref_id is lowercase kebab-case and must be declared in the skill references manifest.
3. path* resolves only to normalized markdown paths under docs/.

Resource Registration Contract

Resources are registered from the validated registry, not by ad hoc per-skill hardcoding.

Registration rules:

1. Use RFC6570 URI templates where appropriate.
2. Mark documentation resources as read-only and idempotent.
3. Set explicit mime types for resource responses.
4. Configure duplicate URI handling with on_duplicate="error" for startup safety.

This keeps runtime behavior deterministic and prevents accidental URI collisions.

Versioning Rule

URIs are unversioned and canonical in this phase.

1. Breaking URI changes are handled as direct replacement.
2. No compatibility aliases or dual URI families are maintained.

Static Hosting Pattern

The docs site is pre-built and served by the same FastAPI runtime process used by the MCP app.

Runtime behavior:

1. App starts.
2. FastAPI mounts the static docs output directory.
3. Requests to docs paths are served as static assets.

This provides a single deployment artifact with no runtime markdown rendering dependency.

Advantages

Single Source of Truth

Methodology is authored once and reused in both MCP resources and docs pages.

High-Fidelity Agent Context

Resources expose the same canonical Markdown that humans author and review.

Operational Simplicity

A single app process serves MCP and docs surfaces.

Long-Term Maintainability

Markdown remains easy to review, while contracts remain stable for clients.

Client Independence

Clients can use Ask, Edit, or Agent modes without requiring server-owned prompt orchestration. However, MCP affordances are still chat-surface-dependent: some clients or sessions expose resource attachment directly, while others make tool invocation the more reliable retrieval path.

Authoring and Publishing Lifecycle

1. Update markdown reference content.
2. Update metadata if capability surface changes.
3. Build static docs with Zensical.
4. Serve built output through FastAPI static mount.

Scope and Non-Goals

In-scope:

1. Resource-first methodology delivery
2. Catalog-based discovery
3. Pre-built static docs hosting in app runtime

Out-of-scope:

1. Prompt-first orchestration as the primary interface
2. Large tool inventories duplicating static guidance across skill modules
3. Separate dynamic docs service at runtime

Allowed exception:

1. A small catalog-level tool layer is acceptable when it improves client interoperability without creating a second source of truth for skill content.

Example Content Inputs

Existing markdown reference sets are valid examples of authored source material for this architecture:

1. docs/skills/pytest-scaffolding/references/pytest-docs.md
2. docs/skills/python-logging-dictconfig/references/python-logging-docs.md
3. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md

These inputs are treated as content sources, while resource URIs and catalog payloads remain the machine-facing contracts.