# nibzard/awesome-agentic-patterns architecture

> Architecture diagram of the GitHub repository nibzard/awesome-agentic-patterns, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nibzard/awesome-agentic-patterns
- Repository: https://github.com/nibzard/awesome-agentic-patterns

## Overview

1. **Repository shape**
   - This is a content-heavy, documentation-first monorepo centered on an Astro website in `apps/web/`, plus a large library of source content in `patterns/` and `research/`.
   - The repo also includes automation for generating, validating, and reviewing pattern entries, along with agent-specific skills under `.claude/`.

2. **Primary product boundary: the website**
   - `apps/web/` is the runtime application. It serves the public catalog, search/browse pages, pattern detail pages, guides, packs, a graph view, and a small API endpoint for newsletter signup.
   - The site is static-site oriented: most pages are content-driven, with data baked into `public/data/*.json` and content collections under `src/content/`.

3. **Content sources and canonical data**
   - The canonical human-authored assets live outside the web app in `patterns/*.md` and `research/*.md`.
   - These pattern markdown files appear to be the source of truth for the catalog entries; the web app consumes generated JSON and derived markdown/MDX-renderable content for presentation.
   - The `research/` folder holds supporting analysis, reports, verification results, and relationship studies that inform or justify pattern entries.

4. **Generation pipeline**
   - The repo uses build/update scripts in `scripts/` to transform pattern markdown into website-ready artifacts.
   - Key outputs include `apps/web/public/patterns.json`, `apps/web/public/data/patterns.json`, `apps/web/public/data/graph.json`, and per-pattern JSON files under `public/data/patterns/`.
   - This creates a clear separation between editable source content and deployable presentation data.

5. **Web app internals**
   - `apps/web/src/content.config.ts` and the `.astro` collection schemas define content types for guides, packs, and patterns.
   - `src/lib/` contains shared data and formatting helpers, including pattern loading, GitHub stars data, markdown processing, and asset-path rewriting.
   - `src/components/` provides reusable UI pieces for cards, filters, search, metadata, navigation, and theme toggling.

6. **User-facing information architecture**
   - The main browsing surfaces are:
     - homepage and discovery pages,
     - `/patterns` index and `/patterns/[slug]` detail pages,
     - `/packs` and `/guides` curated collections,
     - `/decision` for guided selection,
     - `/graph` for relationship visualization.
   - This suggests the application is optimized for exploration and recommendation rather than transactional workflows.

7. **API and dynamic runtime boundary**
   - The site is mostly static, but `apps/web/src/pages/api/subscribe.ts` introduces a serverless boundary for newsletter subscription.
   - That API endpoint is the main dynamic execution point in an otherwise content-rendered architecture.

8. **Automation and validation**
   - Root-level scripts such as `build-data.ts`, `validate-patterns.ts`, `migrate-patterns.ts`, and `fix_pattern_quality.py` support content hygiene and regeneration.
   - Validation is important here because the repository’s product quality depends on schema consistency, metadata correctness, and generated indexes staying in sync with source markdown.

9. **Agent and review workflows**
   - The `.claude/skills/` and `skills/` directories contain operational workflows for pattern creation, arXiv discovery, similarity checking, validation, and PR review.
   - These skills imply an AI-assisted editorial pipeline: discover candidate patterns, compare against existing entries, validate structure, then review via pull-request workflows.

10. **Governance and collaboration**
   - GitHub is the coordination layer for contribution intake, issue templates, pull request templates, and CI.
   - The repo includes governance/documentation files such as `CONTRIBUTING.md`, `SPECIFICATION.md`, `SCHEMA.md`, `TEMPLATE.md`, and policy docs, which act as structural contracts for contributors and automation alike.

11. **CI/CD and deployment**
   - GitHub Actions in `.github/workflows/` handle CI, issue commenting, and pattern review automation.
   - Deployment is targeted at Vercel, with `vercel.json` at the root and `apps/web` as the deployable Astro app.
   - The architecture is therefore: markdown/content source → generation/validation scripts → Astro build → Vercel-hosted static site plus lightweight serverless API.

12. **External data and derived artifacts**
   - The repo ships precomputed artifacts such as `llms.txt`, `llms-full.txt`, Lighthouse reports, sitemap, RSS, and graph data for machine and human consumption.
   - These artifacts indicate the project is designed to be indexable by both search engines and LLM tools, with machine-readable summaries treated as first-class deliverables.

13. **Architectural takeaway**
   - The core design is a **content pipeline with a static presentation layer**: contributors and automation maintain structured pattern knowledge; build scripts compile it into website assets; Astro renders the catalog; Vercel serves it.
   - The main diagram should emphasize the boundary between editable source materials, generated data products, and the public-facing discovery site.

Main entry points: [`apps/web`](https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web) (Web app), [`scripts/build-data.ts`](https://github.com/nibzard/awesome-agentic-patterns/blob/main/scripts/build-data.ts) (Build data), [`patterns`](https://github.com/nibzard/awesome-agentic-patterns/tree/main/patterns) (Patterns), [`scripts/validate-patterns.ts`](https://github.com/nibzard/awesome-agentic-patterns/blob/main/scripts/validate-patterns.ts) (Validate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source content"]
  node_patterns["Patterns<br/>markdown corpus"]
  node_research["Research<br/>analysis corpus"]
end

subgraph group_pipeline["Build pipeline"]
  node_scripts_build["Build data<br/>transform scripts<br/>[build-data.ts]"]
  node_scripts_validate["Validate<br/>quality checks"]
  node_scripts_migrate["Migrate patterns<br/>content migration"]
  node_scripts_quality["Fix quality<br/>repair automation"]
end

subgraph group_web["Public site"]
  node_web_app["Web app<br/>Astro site"]
  node_content_config["Content schema<br/>Astro collections<br/>[content.config.ts]"]
  node_web_data[("Public data<br/>generated assets")]
  node_web_content["Site content<br/>MDX content"]
  node_lib_helpers["Lib helpers<br/>data utilities"]
  node_ui_components["UI components<br/>presentation layer"]
  node_pages_catalog["Catalog pages<br/>routes"]
  node_api_subscribe["Subscribe API<br/>serverless endpoint<br/>[subscribe.ts]"]
  node_llms_outputs["LLMS artifacts<br/>machine-readable outputs<br/>[llms.txt]"]
end

subgraph group_ops["Governance and automation"]
  node_github_workflows["GitHub Actions<br/>ci automation<br/>[workflows]"]
  node_claude_skills["Claude skills<br/>agent workflows<br/>[skills]"]
  node_pr_review_skill["PR review<br/>review workflow"]
  node_governance_docs["Governance docs<br/>repo contracts<br/>[CONTRIBUTING.md]"]
  node_vercel["Vercel deploy<br/>hosting config<br/>[vercel.json]"]
end

node_patterns -->|"source input"| node_scripts_build
node_research -->|"evidence input"| node_scripts_build
node_scripts_build -->|"writes"| node_web_data
node_scripts_build -->|"publishes"| node_llms_outputs
node_scripts_validate -->|"checks"| node_patterns
node_scripts_migrate -->|"updates"| node_patterns
node_scripts_quality -->|"repairs"| node_patterns
node_web_app -->|"defines schema"| node_content_config
node_web_app -->|"renders"| node_web_content
node_web_app -->|"consumes"| node_web_data
node_web_app -->|"uses"| node_lib_helpers
node_web_app -->|"composes"| node_ui_components
node_web_app -->|"serves"| node_pages_catalog
node_pages_catalog -->|"invokes"| node_api_subscribe
node_github_workflows -->|"runs"| node_scripts_validate
node_github_workflows -->|"runs"| node_scripts_build
node_claude_skills -->|"assists"| node_scripts_build
node_claude_skills -->|"assists"| node_scripts_validate
node_pr_review_skill -->|"integrates"| node_github_workflows
node_governance_docs -->|"contracts"| node_scripts_validate
node_governance_docs -->|"guides"| node_claude_skills
node_vercel -->|"deploys"| node_web_app

click node_patterns "https://github.com/nibzard/awesome-agentic-patterns/tree/main/patterns"
click node_research "https://github.com/nibzard/awesome-agentic-patterns/tree/main/research"
click node_scripts_build "https://github.com/nibzard/awesome-agentic-patterns/blob/main/scripts/build-data.ts"
click node_scripts_validate "https://github.com/nibzard/awesome-agentic-patterns/blob/main/scripts/validate-patterns.ts"
click node_scripts_migrate "https://github.com/nibzard/awesome-agentic-patterns/blob/main/scripts/migrate-patterns.ts"
click node_scripts_quality "https://github.com/nibzard/awesome-agentic-patterns/blob/main/scripts/fix_pattern_quality.py"
click node_web_app "https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web"
click node_content_config "https://github.com/nibzard/awesome-agentic-patterns/blob/main/apps/web/src/content.config.ts"
click node_web_data "https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web/public/data"
click node_web_content "https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web/src/content"
click node_lib_helpers "https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web/src/lib"
click node_ui_components "https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web/src/components"
click node_pages_catalog "https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web/src/pages"
click node_api_subscribe "https://github.com/nibzard/awesome-agentic-patterns/blob/main/apps/web/src/pages/api/subscribe.ts"
click node_llms_outputs "https://github.com/nibzard/awesome-agentic-patterns/blob/main/apps/web/public/llms.txt"
click node_github_workflows "https://github.com/nibzard/awesome-agentic-patterns/blob/main/.github/workflows"
click node_claude_skills "https://github.com/nibzard/awesome-agentic-patterns/blob/main/.claude/skills"
click node_pr_review_skill "https://github.com/nibzard/awesome-agentic-patterns/tree/main/skills/pr-review"
click node_governance_docs "https://github.com/nibzard/awesome-agentic-patterns/blob/main/CONTRIBUTING.md"
click node_vercel "https://github.com/nibzard/awesome-agentic-patterns/blob/main/vercel.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_patterns,node_research toneBlue
class node_scripts_build,node_scripts_validate,node_scripts_migrate,node_scripts_quality toneAmber
class node_web_app,node_content_config,node_web_data,node_web_content,node_lib_helpers,node_ui_components,node_pages_catalog,node_api_subscribe,node_llms_outputs toneMint
class node_github_workflows,node_claude_skills,node_pr_review_skill,node_governance_docs,node_vercel toneRose
```

## Components

### Source content

Canonical markdown and supporting research that define the pattern catalog.

- [Patterns](https://github.com/nibzard/awesome-agentic-patterns/tree/main/patterns): markdown corpus · Canonical pattern entries authored as markdown. · `patterns`
- [Research](https://github.com/nibzard/awesome-agentic-patterns/tree/main/research): analysis corpus · Supporting reports, comparisons, and verification material for patterns. · `research`

### Build pipeline

Scripts and automation that transform source content into deployable artifacts.

- [Build data](https://github.com/nibzard/awesome-agentic-patterns/blob/main/scripts/build-data.ts): transform scripts · Generates website-ready JSON and derived artifacts from source content. · `scripts/build-data.ts`
- [Validate](https://github.com/nibzard/awesome-agentic-patterns/blob/main/scripts/validate-patterns.ts): quality checks · Checks schema consistency and content correctness across pattern entries. · `scripts/validate-patterns.ts`
- [Migrate patterns](https://github.com/nibzard/awesome-agentic-patterns/blob/main/scripts/migrate-patterns.ts): content migration · Updates pattern sources and structures during repository evolution. · `scripts/migrate-patterns.ts`
- [Fix quality](https://github.com/nibzard/awesome-agentic-patterns/blob/main/scripts/fix_pattern_quality.py): repair automation · Python-based cleanup and normalization for pattern content. · `scripts/fix_pattern_quality.py`

### Public site

Astro application that renders the catalog and related discovery surfaces.

- [Web app](https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web): Astro site · Deployable Astro application that serves the public catalog. · `apps/web`
- [Content schema](https://github.com/nibzard/awesome-agentic-patterns/blob/main/apps/web/src/content.config.ts): Astro collections · Defines content collections and schemas for guides, packs, and patterns. · `apps/web/src/content.config.ts`
- [Public data](https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web/public/data): generated assets · Compiled JSON, graph data, patterns, and machine-readable site outputs. · `apps/web/public/data`
- [Site content](https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web/src/content): MDX content · Guides and packs rendered directly by the site. · `apps/web/src/content`
- [Lib helpers](https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web/src/lib): data utilities · Loading, formatting, markdown, and asset-path helpers shared by pages and components. · `apps/web/src/lib`
- [UI components](https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web/src/components): presentation layer · Reusable cards, filters, search, navigation, and metadata components. · `apps/web/src/components`
- [Catalog pages](https://github.com/nibzard/awesome-agentic-patterns/tree/main/apps/web/src/pages): routes · Homepage, patterns, packs, guides, decision, and graph browsing surfaces. · `apps/web/src/pages`
- [Subscribe API](https://github.com/nibzard/awesome-agentic-patterns/blob/main/apps/web/src/pages/api/subscribe.ts): serverless endpoint · Newsletter signup endpoint providing the main dynamic runtime boundary. · `apps/web/src/pages/api/subscribe.ts`
- [LLMS artifacts](https://github.com/nibzard/awesome-agentic-patterns/blob/main/apps/web/public/llms.txt): machine-readable outputs · Precomputed text and report artifacts for search and model ingestion. · `apps/web/public/llms.txt`

### Governance and automation

Contribution, CI, and agent workflows that maintain the repository.

- [GitHub Actions](https://github.com/nibzard/awesome-agentic-patterns/blob/main/.github/workflows): ci automation · CI, issue comment, and pattern review workflows. · `.github/workflows`
- [Claude skills](https://github.com/nibzard/awesome-agentic-patterns/blob/main/.claude/skills): agent workflows · Operational skills for discovery, creation, validation, and review. · `.claude/skills`
- [PR review](https://github.com/nibzard/awesome-agentic-patterns/tree/main/skills/pr-review): review workflow · Human/agent review workflow for pull requests. · `skills/pr-review`
- [Governance docs](https://github.com/nibzard/awesome-agentic-patterns/blob/main/CONTRIBUTING.md): repo contracts · Contribution, schema, specification, and policy documents that constrain content and automation. · `CONTRIBUTING.md`
- [Vercel deploy](https://github.com/nibzard/awesome-agentic-patterns/blob/main/vercel.json): hosting config · Deployment target for the Astro site. · `vercel.json`

## Connections

- Patterns → Build data: source input · Pattern markdown is compiled into deployable data.
- Research → Build data: evidence input · Research material informs generated catalog artifacts.
- Build data → Public data: writes · Build scripts emit JSON and derived public data.
- Build data → LLMS artifacts: publishes · Build outputs also include machine-readable summaries.
- Validate → Patterns: checks · Validation enforces content shape and schema correctness.
- Migrate patterns → Patterns: updates · Migration scripts reshape pattern sources over time.
- Fix quality → Patterns: repairs · Quality fixes normalize or correct pattern markdown.
- Web app → Content schema: defines schema · The Astro app declares content collections and types.
- Web app → Site content: renders · Guides and packs are rendered from site content.
- Web app → Public data: consumes · The site reads generated pattern and graph data.
- Web app → Lib helpers: uses · Pages and components share loading and formatting logic.
- Web app → UI components: composes · The site UI is assembled from reusable components.
- Web app → Catalog pages: serves · Primary discovery and detail routes live here.
- Catalog pages → Subscribe API: invokes · The public site exposes a lightweight dynamic endpoint.
- GitHub Actions → Validate: runs · CI and review automation execute validation checks.
- GitHub Actions → Build data: runs · Workflow automation rebuilds generated artifacts.
- Claude skills → Build data: assists · Agent workflows support content discovery and generation.
- Claude skills → Validate: assists · Agent workflows support validation and review.
- PR review → GitHub Actions: integrates · PR review participates in repository coordination.
- Governance docs → Validate: contracts · Repo docs define expected structure and constraints.
- Governance docs → Claude skills: guides · Policies and templates guide agent-assisted workflows.
- Vercel deploy → Web app: deploys · Hosting is targeted at the Astro application.
