---
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](./content.md)
2. [Frontmatter Contract](./frontmatter.md)
3. [URI Contract](./uris.md)

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

```mermaid
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](./frontmatter.md).

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. optional references map (for nested entries, overrides, and aliases)

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](./uris.md).

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 resolve from either:
    - top-level auto-discovery of `references/*.md` filename stems, or
    - an explicit `x-personal-mcp.references` entry.
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.