prompts/docs/architecture.md

icon

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 four layers:

1. Pattern modules expose methodology as MCP resources.
2. Catalog resources provide normalized discovery.
3. A docs export step materializes resource content into markdown.
4. Zensical builds a static site that is served by the FastAPI app 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. overview
2. rules
3. checklist
4. references

Tools are intentionally narrow and optional. They exist only for deterministic export-like behavior.

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 load authored content and expose it through stable resource URIs.

Static Docs Surface

Static docs are generated from two merged content streams:

1. Project-authored docs pages
2. Generated pages derived from MCP resources

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]
    C --> E[Docs Export Step]
    D --> E
    E --> F[Generated Docs Markdown]
    F --> G[Zensical Static Build]
    G --> H[FastAPI Static Mount]
    H --> I[Served Docs Site]

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>/overview
2. resource://skills/<skill_id>/rules
3. resource://skills/<skill_id>/checklist
4. resource://skills/<skill_id>/references

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 explicit, attachable context for accurate implementation behavior.

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. Run resource export to generated docs markdown.
4. Build static docs with Zensical.
5. 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.