# majiayu000/spellbook architecture

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

- Interactive diagram: https://gitdiagram.com/majiayu000/spellbook
- Repository: https://github.com/majiayu000/spellbook

## Overview

Spellbook is a cross-runtime catalog of reusable agent skills. The documented user workflow is to choose a skill or job-shaped bundle, install it for a supported agent, then invoke it in that agent; the README also describes an advanced installer for Claude Code agents. The tree and excerpts show representative skill scripts and project templates, not the full catalog or installer implementation. The graph preserves the documented capability branches and sampled template modules; some internal routes and runtime behavior are therefore left unconnected.

Main entry points: [`skills/python-project/templates/api/src/myapp/main.py`](https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/main.py) (Python API template), [`skills`](https://github.com/majiayu000/spellbook/tree/main/skills) (Skill catalog), [`skills/python-project/templates/api/src/myapp/services/user.py`](https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/services/user.py) (User service), [`skills/typescript-project/templates/project/src/adapters/llm.adapter.ts`](https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/adapters/llm.adapter.ts) (LLM adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Skill catalog"]
  node_skills["Skill catalog"]
  node_workflow_bundles["Workflow bundles"]
end

subgraph group_templates["Project templates"]
  node_api_template["Python API template<br/>[main.py]"]
  node_api_user_route["User API route<br/>[user.py]"]
  node_api_middleware["API middleware<br/>[middleware.py]"]
  node_api_config["API configuration<br/>[config.py]"]
  node_api_exceptions["API exceptions<br/>[exceptions.py]"]
  node_api_logging["API logging<br/>[logging.py]"]
  node_api_models["User models<br/>[user.py]"]
  node_api_service["User service<br/>[user.py]"]
  node_rust_cli["Rust CLI<br/>[main.rs]"]
  node_rust_commands["CLI commands<br/>[process.rs]"]
  node_rust_web_router["Rust web router<br/>[router.rs]"]
  node_rust_web_handlers["Web handlers<br/>[user.rs]"]
  node_rust_web_model["Web user model<br/>[user.rs]"]
  node_ts_service["Example service<br/>[example.service.ts]"]
  node_ts_repository[("Memory repository")]
  node_ts_llm["LLM adapter<br/>[llm.adapter.ts]"]
  node_ts_config["App configuration<br/>[config.ts]"]
  node_ts_logger["App logger<br/>[logger.ts]"]
  node_ts_errors["App errors<br/>[errors.ts]"]
end

subgraph group_motion["Media workflow"]
  node_motion_render["Scene renderer<br/>[render.mjs]"]
  node_motion_env["FFmpeg discovery<br/>[env.mjs]"]
end

subgraph group_agent["Agent workflows"]
  node_luna_worker["Luna worker<br/>[run_luna_worker.py]"]
  node_luna_events["Worker events<br/>[worker_events.py]"]
end

node_user(("Agent user"))
node_runtime["Claude Code / Codex"]

node_user -->|"chooses workflow"| node_workflow_bundles
node_user -->|"selects skills"| node_skills
node_skills -->|"installs into"| node_runtime
node_workflow_bundles -->|"bundles skills"| node_skills
node_api_template -->|"registers handlers"| node_api_middleware
node_api_template -->|"reads settings"| node_api_config
node_api_template -->|"sets up logging"| node_api_logging
node_api_service -->|"raises errors"| node_api_exceptions
node_api_service -->|"creates models"| node_api_models
node_rust_cli -->|"executes command"| node_rust_commands
node_rust_web_router -->|"routes requests"| node_rust_web_handlers
node_motion_render -->|"finds FFmpeg"| node_motion_env
node_ts_service -->|"uses repository"| node_ts_repository
node_ts_llm -->|"reads settings"| node_ts_config
node_ts_llm -->|"logs requests"| node_ts_logger
node_luna_worker -->|"uses events"| node_luna_events

click node_skills "https://github.com/majiayu000/spellbook/tree/main/skills"
click node_workflow_bundles "https://github.com/majiayu000/spellbook/tree/main/skills"
click node_api_template "https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/main.py"
click node_api_user_route "https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/api/routes/user.py"
click node_api_middleware "https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/api/middleware.py"
click node_api_config "https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/config.py"
click node_api_exceptions "https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/core/exceptions.py"
click node_api_logging "https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/core/logging.py"
click node_api_models "https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/models/user.py"
click node_api_service "https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/services/user.py"
click node_rust_cli "https://github.com/majiayu000/spellbook/blob/main/skills/rust-project/templates/cli/src/main.rs"
click node_rust_commands "https://github.com/majiayu000/spellbook/blob/main/skills/rust-project/templates/cli/src/commands/process.rs"
click node_rust_web_router "https://github.com/majiayu000/spellbook/blob/main/skills/rust-project/templates/web-service/src/router.rs"
click node_rust_web_handlers "https://github.com/majiayu000/spellbook/blob/main/skills/rust-project/templates/web-service/src/handlers/user.rs"
click node_rust_web_model "https://github.com/majiayu000/spellbook/blob/main/skills/rust-project/templates/web-service/src/models/user.rs"
click node_motion_render "https://github.com/majiayu000/spellbook/blob/main/skills/motion-stack/kit/render.mjs"
click node_motion_env "https://github.com/majiayu000/spellbook/blob/main/skills/motion-stack/kit/env.mjs"
click node_ts_service "https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/services/example.service.ts"
click node_ts_repository "https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/adapters/in-memory.repository.ts"
click node_ts_llm "https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/adapters/llm.adapter.ts"
click node_ts_config "https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/lib/config.ts"
click node_ts_logger "https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/lib/logger.ts"
click node_ts_errors "https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/lib/errors.ts"
click node_luna_worker "https://github.com/majiayu000/spellbook/blob/main/skills/sol-luna-router/scripts/run_luna_worker.py"
click node_luna_events "https://github.com/majiayu000/spellbook/blob/main/skills/sol-luna-router/scripts/worker_events.py"

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_skills,node_workflow_bundles,node_user toneBlue
class node_api_template,node_api_user_route,node_api_middleware,node_api_config,node_api_exceptions,node_api_logging,node_api_models,node_api_service,node_rust_cli,node_rust_commands,node_rust_web_router,node_rust_web_handlers,node_rust_web_model,node_ts_service,node_ts_repository,node_ts_llm,node_ts_config,node_ts_logger,node_ts_errors toneAmber
class node_motion_render,node_motion_env toneMint
class node_luna_worker,node_luna_events toneRose
class node_runtime toneIndigo
```

## Components

### Skill catalog

- [Skill catalog](https://github.com/majiayu000/spellbook/tree/main/skills): `skills`
- [Workflow bundles](https://github.com/majiayu000/spellbook/tree/main/skills): `skills`

### Project templates

- [Python API template](https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/main.py): `skills/python-project/templates/api/src/myapp/main.py`
- [User API route](https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/api/routes/user.py): `skills/python-project/templates/api/src/myapp/api/routes/user.py`
- [API middleware](https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/api/middleware.py): `skills/python-project/templates/api/src/myapp/api/middleware.py`
- [API configuration](https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/config.py): `skills/python-project/templates/api/src/myapp/config.py`
- [API exceptions](https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/core/exceptions.py): `skills/python-project/templates/api/src/myapp/core/exceptions.py`
- [API logging](https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/core/logging.py): `skills/python-project/templates/api/src/myapp/core/logging.py`
- [User models](https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/models/user.py): `skills/python-project/templates/api/src/myapp/models/user.py`
- [User service](https://github.com/majiayu000/spellbook/blob/main/skills/python-project/templates/api/src/myapp/services/user.py): `skills/python-project/templates/api/src/myapp/services/user.py`
- [Rust CLI](https://github.com/majiayu000/spellbook/blob/main/skills/rust-project/templates/cli/src/main.rs): `skills/rust-project/templates/cli/src/main.rs`
- [CLI commands](https://github.com/majiayu000/spellbook/blob/main/skills/rust-project/templates/cli/src/commands/process.rs): `skills/rust-project/templates/cli/src/commands/process.rs`
- [Rust web router](https://github.com/majiayu000/spellbook/blob/main/skills/rust-project/templates/web-service/src/router.rs): `skills/rust-project/templates/web-service/src/router.rs`
- [Web handlers](https://github.com/majiayu000/spellbook/blob/main/skills/rust-project/templates/web-service/src/handlers/user.rs): `skills/rust-project/templates/web-service/src/handlers/user.rs`
- [Web user model](https://github.com/majiayu000/spellbook/blob/main/skills/rust-project/templates/web-service/src/models/user.rs): `skills/rust-project/templates/web-service/src/models/user.rs`
- [Example service](https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/services/example.service.ts): `skills/typescript-project/templates/project/src/services/example.service.ts`
- [Memory repository](https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/adapters/in-memory.repository.ts): `skills/typescript-project/templates/project/src/adapters/in-memory.repository.ts`
- [LLM adapter](https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/adapters/llm.adapter.ts): `skills/typescript-project/templates/project/src/adapters/llm.adapter.ts`
- [App configuration](https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/lib/config.ts): `skills/typescript-project/templates/project/src/lib/config.ts`
- [App logger](https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/lib/logger.ts): `skills/typescript-project/templates/project/src/lib/logger.ts`
- [App errors](https://github.com/majiayu000/spellbook/blob/main/skills/typescript-project/templates/project/src/lib/errors.ts): `skills/typescript-project/templates/project/src/lib/errors.ts`

### Media workflow

- [Scene renderer](https://github.com/majiayu000/spellbook/blob/main/skills/motion-stack/kit/render.mjs): `skills/motion-stack/kit/render.mjs`
- [FFmpeg discovery](https://github.com/majiayu000/spellbook/blob/main/skills/motion-stack/kit/env.mjs): `skills/motion-stack/kit/env.mjs`

### Agent workflows

- [Luna worker](https://github.com/majiayu000/spellbook/blob/main/skills/sol-luna-router/scripts/run_luna_worker.py): `skills/sol-luna-router/scripts/run_luna_worker.py`
- [Worker events](https://github.com/majiayu000/spellbook/blob/main/skills/sol-luna-router/scripts/worker_events.py): `skills/sol-luna-router/scripts/worker_events.py`

### Other components

- **Agent user**
- **Claude Code / Codex**

## Connections

- Agent user → Workflow bundles: chooses workflow (evidence: `README.md`)
- Agent user → Skill catalog: selects skills (evidence: `README.md`)
- Skill catalog → Claude Code / Codex: installs into (evidence: `README.md`)
- Workflow bundles → Skill catalog: bundles skills (evidence: `README.md`)
- Python API template → API middleware: registers handlers (evidence: `skills/python-project/templates/api/src/myapp/main.py`)
- Python API template → API configuration: reads settings (evidence: `skills/python-project/templates/api/src/myapp/main.py`)
- Python API template → API logging: sets up logging (evidence: `skills/python-project/templates/api/src/myapp/main.py`)
- User service → API exceptions: raises errors (evidence: `skills/python-project/templates/api/src/myapp/services/user.py`)
- User service → User models: creates models (evidence: `skills/python-project/templates/api/src/myapp/services/user.py`)
- Rust CLI → CLI commands: executes command (evidence: `skills/rust-project/templates/cli/src/main.rs`)
- Rust web router → Web handlers: routes requests (evidence: `skills/rust-project/templates/web-service/src/router.rs`)
- Scene renderer → FFmpeg discovery: finds FFmpeg (evidence: `skills/motion-stack/kit/render.mjs`)
- Example service → Memory repository: uses repository (evidence: `skills/typescript-project/templates/project/src/services/example.service.ts`)
- LLM adapter → App configuration: reads settings (evidence: `skills/typescript-project/templates/project/src/adapters/llm.adapter.ts`)
- LLM adapter → App logger: logs requests (evidence: `skills/typescript-project/templates/project/src/adapters/llm.adapter.ts`)
- Luna worker → Worker events: uses events (evidence: `skills/sol-luna-router/scripts/run_luna_worker.py`)
