---
icon: lucide/library
---

# Resource-First Pattern Module 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.

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 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.
3. Public documentation must be pre-built static output served from the application runtime without a separate docs service.

## System Model

### Pattern Modules

Each module encapsulates one methodology domain and 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.

Typical catalog resources:

1. resource://catalog/patterns
2. resource://catalog/patterns_by_id
3. resource://catalog/skills_index
4. resource://catalog/skills_details

### Content Sources

Content is authored in markdown and managed as long-form reference material. 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 pattern module declares:

1. id
2. name
3. version
4. description
5. tags
6. capabilities
7. depends_on

### URI Contract

Module resource URIs are stable and follow:

1. resource://skills/<skill_id>/document

Catalog resource URIs are stable and discovery-focused.

### Versioning Rule

Published URIs are immutable. Behavioral or schema changes are versioned in metadata and documented through additive migration notes.

## 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.

## 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
3. Separate dynamic docs service at runtime

## Example Content Inputs

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

1. ../skills/pytest-scaffolding/references/pytest-docs.md
2. ../skills/python-logging-dictconfig/references/python-logging-docs.md
3. ../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.