John Lancaster
173 lines
4.8 KiB
Markdown
173 lines
4.8 KiB
Markdown
---
|
|
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
|
|
|
|
```mermaid
|
|
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.
|