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 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 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. 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/patterns
2. resource://catalog/patterns_by_id
3. resource://catalog/skills_index
4. resource://catalog/skills_details

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