Skip to content

docs: use rendered Mermaid diagrams in Architecture.md #135

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
suleimansh merged 1 commit into from
Jul 2, 2026
Merged

docs: use rendered Mermaid diagrams in Architecture.md #135

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions Architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,9 @@ GemStack hosts **framework-agnostic engines** that work in any Node app. It does
- **Engines (belong here):** `@gemstack/ai-sdk` and its family. They have no hard dependency on any framework.
- **Bindings (do not belong here):** framework extensions like the `vike-*` packages (in the `vike-data` repo). Their whole value is the framework integration, so they are the opposite of agnostic. They live with their framework and **consume** GemStack engines, e.g. `vike-ai` is a thin Vike binding over `@gemstack/ai-sdk`:

```
@gemstack/ai-sdk (agnostic engine, here)
^
| thin binding
vike-ai (Vike extension, in vike-data) -- consumes the engine
```mermaid
graph TD
vikeai["<b>vike-ai</b><br/>Vike extension · in vike-data"] -->|"thin binding, consumes"| sdk["<b>@gemstack/ai-sdk</b><br/>agnostic engine · here"]
```

### Graduation, not bulk relocation
Expand Down Expand Up @@ -48,13 +46,16 @@ When a candidate does graduate, follow the `@gemstack/ai-sdk` playbook exactly:

## The AI family

```
@gemstack/ai-sdk agent runtime (the "verbs")
@gemstack/ai-skills capability bundles (the composable "nouns") -> ai-sdk
@gemstack/ai-autopilot orchestration / autonomy (the "director") -> ai-sdk (+ skills)
@gemstack/ai-mcp agent <-> MCP bridge (the "adapter") -> ai-sdk
-----------------------------------------------------------------------------------
@gemstack/mcp standalone MCP server framework agent-agnostic, NOT ai-*
```mermaid
graph TD
subgraph fam["AI family · depends on the agent runtime"]
skills["<b>ai-skills</b><br/>capability bundles"] --> sdk["<b>ai-sdk</b><br/>agent runtime"]
autopilot["<b>ai-autopilot</b><br/>orchestration"] --> sdk
aimcp["<b>ai-mcp</b><br/>agent ↔ MCP bridge"] --> sdk
end
subgraph agn["Agent-agnostic · not ai-*"]
connstar["<b>connector-*</b><br/>first-party connectors"] --> connectors["<b>connectors</b><br/>connector contract"] --> mcp["<b>mcp</b><br/>MCP server framework"]
end
```

### Dependency direction (the one rule that keeps four packages from becoming a tangle)
Expand Down
Loading