docs
This commit is contained in:
John Lancaster
@@ -0,0 +1,172 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user