John Lancaster
167 lines
5.2 KiB
Markdown
167 lines
5.2 KiB
Markdown
---
|
|
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.
|
|
|
|
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
|
|
|
|
```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. 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.
|