# patrickbrandao/purple-skills architecture

> Architecture diagram of the GitHub repository patrickbrandao/purple-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/patrickbrandao/purple-skills
- Repository: https://github.com/patrickbrandao/purple-skills

## Overview

Purple Skills hosts reusable AI-agent skills and exposes them through a public catalog site, an administration panel, and public and administrative MCP servers. The main workflow is publishing or importing a skill, managing its access and catalog links, then letting visitors or agents discover and retrieve it. PostgreSQL stores catalog and account state; an optional RAG subsystem adds semantic search, with an indexer maintaining search data. The homepage is a separate static project overview. Relationships for unsampled services are limited to capabilities and wiring documented in the README; source excerpts provide more specific MCP dispatch and database/RAG evidence.

Main entry points: [`database/src/queries.ts`](https://github.com/patrickbrandao/purple-skills/blob/main/database/src/queries.ts) (Catalog queries), [`apps/mcp-admin/src/server.ts`](https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-admin/src/server.ts) (Admin MCP), [`apps/admin/src/api.ts`](https://github.com/patrickbrandao/purple-skills/blob/main/apps/admin/src/api.ts) (Admin service), [`apps/mcp-public/src/tools.ts`](https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-public/src/tools.ts) (Public MCP handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_homepage["Project homepage<br/>[App.tsx]"]
end

subgraph group_catalog["Catalog Experience"]
  node_siteui["Public catalog UI<br/>[SkillPage.tsx]"]
  node_siteapi["Public site service<br/>[index.ts]"]
end

subgraph group_admin["Administration"]
  node_adminui["Admin panel<br/>[App.tsx]"]
  node_adminapi["Admin service<br/>[api.ts]"]
  node_adminrag["Admin RAG controls<br/>[rag.ts]"]
end

subgraph group_mcp["MCP Services"]
  node_mcpadmin["Admin MCP<br/>[server.ts]"]
  node_adminhandlers["Admin MCP handlers<br/>[tools.ts]"]
  node_cataloghandlers["Catalog handlers<br/>[catalogs.ts]"]
  node_mcphandlers["Virtual MCP handlers<br/>[mcps.ts]"]
  node_publicmcp["Public MCP<br/>[server.ts]"]
  node_publichandlers["Public MCP handlers<br/>[tools.ts]"]
  node_mcp_rag["Public MCP RAG adapter<br/>[rag.ts]"]
end

subgraph group_data["Data and Search"]
  node_dbclient["Database connection<br/>[client.ts]"]
  node_queries["Catalog queries<br/>[queries.ts]"]
  node_schema[("PostgreSQL schema<br/>[schema.ts]")]
  node_ragsearch["RAG search<br/>[search.ts]"]
  node_ragsettings["RAG drivers and settings<br/>[settings.ts]"]
  node_indexer["Search indexer<br/>[indexer.ts]"]
end

node_visitor(("Visitor or agent"))

node_visitor -->|"views overview"| node_homepage
node_visitor -->|"browses skills"| node_siteui
node_siteui -->|"requests catalog"| node_siteapi
node_visitor -->|"manages catalog"| node_adminui
node_adminui -->|"calls API"| node_adminapi
node_adminapi -->|"reads and writes"| node_queries
node_mcpadmin -->|"dispatches tools"| node_adminhandlers
node_mcpadmin -->|"dispatches catalog tools"| node_cataloghandlers
node_mcpadmin -->|"dispatches MCP tools"| node_mcphandlers
node_adminhandlers -->|"manages skills"| node_queries
node_cataloghandlers -->|"manages catalogs"| node_queries
node_mcphandlers -->|"manages virtual MCPs"| node_queries
node_visitor -->|"uses MCP tools"| node_publicmcp
node_publicmcp -->|"dispatches tools"| node_publichandlers
node_publichandlers -->|"discovers and reads"| node_queries
node_dbclient -->|"binds schema"| node_schema
node_queries -->|"uses connection"| node_dbclient
node_adminapi -->|"exposes search settings"| node_adminrag
node_adminrag -->|"stores RAG settings"| node_queries
node_publichandlers -->|"requests semantic search"| node_mcp_rag
node_mcp_rag -->|"configures search"| node_ragsearch
node_ragsearch -->|"resolves driver"| node_ragsettings
node_indexer -->|"uses RAG drivers"| node_ragsettings

click node_homepage "https://github.com/patrickbrandao/purple-skills/blob/main/apps/homepage/web/src/App.tsx"
click node_siteui "https://github.com/patrickbrandao/purple-skills/blob/main/apps/site/web/src/pages/SkillPage.tsx"
click node_siteapi "https://github.com/patrickbrandao/purple-skills/blob/main/apps/site/src/index.ts"
click node_adminui "https://github.com/patrickbrandao/purple-skills/blob/main/apps/admin/web/src/App.tsx"
click node_adminapi "https://github.com/patrickbrandao/purple-skills/blob/main/apps/admin/src/api.ts"
click node_mcpadmin "https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-admin/src/server.ts"
click node_adminhandlers "https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-admin/src/tools.ts"
click node_cataloghandlers "https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-admin/src/catalogs.ts"
click node_mcphandlers "https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-admin/src/mcps.ts"
click node_publicmcp "https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-public/src/server.ts"
click node_publichandlers "https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-public/src/tools.ts"
click node_dbclient "https://github.com/patrickbrandao/purple-skills/blob/main/database/src/client.ts"
click node_queries "https://github.com/patrickbrandao/purple-skills/blob/main/database/src/queries.ts"
click node_schema "https://github.com/patrickbrandao/purple-skills/blob/main/database/src/schema.ts"
click node_ragsearch "https://github.com/patrickbrandao/purple-skills/blob/main/packages/rag/src/search.ts"
click node_ragsettings "https://github.com/patrickbrandao/purple-skills/blob/main/packages/rag/src/settings.ts"
click node_mcp_rag "https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-public/src/rag.ts"
click node_adminrag "https://github.com/patrickbrandao/purple-skills/blob/main/apps/admin/src/rag.ts"
click node_indexer "https://github.com/patrickbrandao/purple-skills/blob/main/apps/indexer/src/indexer.ts"

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_homepage toneBlue
class node_siteui,node_siteapi toneAmber
class node_adminui,node_adminapi,node_adminrag toneMint
class node_mcpadmin,node_adminhandlers,node_cataloghandlers,node_mcphandlers,node_publicmcp,node_publichandlers,node_mcp_rag toneRose
class node_dbclient,node_queries,node_schema,node_ragsearch,node_ragsettings,node_indexer,node_visitor toneIndigo
```

## Components

### Presentation

- [Project homepage](https://github.com/patrickbrandao/purple-skills/blob/main/apps/homepage/web/src/App.tsx): `apps/homepage/web/src/App.tsx`

### Catalog Experience

- [Public catalog UI](https://github.com/patrickbrandao/purple-skills/blob/main/apps/site/web/src/pages/SkillPage.tsx): `apps/site/web/src/pages/SkillPage.tsx`
- [Public site service](https://github.com/patrickbrandao/purple-skills/blob/main/apps/site/src/index.ts): `apps/site/src/index.ts`

### Administration

- [Admin panel](https://github.com/patrickbrandao/purple-skills/blob/main/apps/admin/web/src/App.tsx): `apps/admin/web/src/App.tsx`
- [Admin service](https://github.com/patrickbrandao/purple-skills/blob/main/apps/admin/src/api.ts): `apps/admin/src/api.ts`
- [Admin RAG controls](https://github.com/patrickbrandao/purple-skills/blob/main/apps/admin/src/rag.ts): `apps/admin/src/rag.ts`

### MCP Services

- [Admin MCP](https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-admin/src/server.ts): `apps/mcp-admin/src/server.ts`
- [Admin MCP handlers](https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-admin/src/tools.ts): `apps/mcp-admin/src/tools.ts`
- [Catalog handlers](https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-admin/src/catalogs.ts): `apps/mcp-admin/src/catalogs.ts`
- [Virtual MCP handlers](https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-admin/src/mcps.ts): `apps/mcp-admin/src/mcps.ts`
- [Public MCP](https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-public/src/server.ts): `apps/mcp-public/src/server.ts`
- [Public MCP handlers](https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-public/src/tools.ts): `apps/mcp-public/src/tools.ts`
- [Public MCP RAG adapter](https://github.com/patrickbrandao/purple-skills/blob/main/apps/mcp-public/src/rag.ts): `apps/mcp-public/src/rag.ts`

### Data and Search

- [Database connection](https://github.com/patrickbrandao/purple-skills/blob/main/database/src/client.ts): `database/src/client.ts`
- [Catalog queries](https://github.com/patrickbrandao/purple-skills/blob/main/database/src/queries.ts): `database/src/queries.ts`
- [PostgreSQL schema](https://github.com/patrickbrandao/purple-skills/blob/main/database/src/schema.ts): `database/src/schema.ts`
- [RAG search](https://github.com/patrickbrandao/purple-skills/blob/main/packages/rag/src/search.ts): `packages/rag/src/search.ts`
- [RAG drivers and settings](https://github.com/patrickbrandao/purple-skills/blob/main/packages/rag/src/settings.ts): `packages/rag/src/settings.ts`
- [Search indexer](https://github.com/patrickbrandao/purple-skills/blob/main/apps/indexer/src/indexer.ts): `apps/indexer/src/indexer.ts`

### Other components

- **Visitor or agent**

## Connections

- Visitor or agent → Project homepage: views overview (evidence: `apps/homepage/web/src/App.tsx`)
- Visitor or agent → Public catalog UI: browses skills (evidence: `README.md`)
- Public catalog UI → Public site service: requests catalog (evidence: `README.md`)
- Visitor or agent → Admin panel: manages catalog (evidence: `README.md`)
- Admin panel → Admin service: calls API
- Admin service → Catalog queries: reads and writes (evidence: `README.md`)
- Admin MCP → Admin MCP handlers: dispatches tools (evidence: `apps/mcp-admin/src/server.ts`)
- Admin MCP → Catalog handlers: dispatches catalog tools (evidence: `apps/mcp-admin/src/server.ts`)
- Admin MCP → Virtual MCP handlers: dispatches MCP tools (evidence: `apps/mcp-admin/src/server.ts`)
- Admin MCP handlers → Catalog queries: manages skills (evidence: `README.md`)
- Catalog handlers → Catalog queries: manages catalogs (evidence: `README.md`)
- Virtual MCP handlers → Catalog queries: manages virtual MCPs (evidence: `README.md`)
- Visitor or agent → Public MCP: uses MCP tools (evidence: `README.md`)
- Public MCP → Public MCP handlers: dispatches tools (evidence: `apps/mcp-public/src/server.ts`)
- Public MCP handlers → Catalog queries: discovers and reads (evidence: `README.md`)
- Database connection → PostgreSQL schema: binds schema (evidence: `database/src/client.ts`)
- Catalog queries → Database connection: uses connection (evidence: `database/src/queries.ts`)
- Admin service → Admin RAG controls: exposes search settings (evidence: `README.md`)
- Admin RAG controls → Catalog queries: stores RAG settings (evidence: `apps/admin/src/rag.ts`)
- Public MCP handlers → Public MCP RAG adapter: requests semantic search (evidence: `apps/mcp-public/src/tools.ts`)
- Public MCP RAG adapter → RAG search: configures search (evidence: `apps/mcp-public/src/rag.ts`)
- RAG search → RAG drivers and settings: resolves driver (evidence: `packages/rag/src/search.ts`)
- Search indexer → RAG drivers and settings: uses RAG drivers (evidence: `apps/indexer/src/indexer.ts`)