From 485b208da63c121a43f8c03cc42d4bac4504015d Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Thu, 19 Mar 2026 16:58:15 +0900 Subject: [PATCH] docs: add art deco architecture diagram to README and docs index Add an SVG architecture diagram showing Perstack's container structure, runtime components, external integrations, security boundary, and infrastructure targets. Embed it in README.md and docs/index.mdx. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 8 ++ docs/architecture.svg | 228 ++++++++++++++++++++++++++++++++++++++++++ docs/index.mdx | 2 + 3 files changed, 238 insertions(+) create mode 100644 docs/architecture.svg diff --git a/README.md b/README.md index f98e33ca..699501b2 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,14 @@ X

+

+ + + + Perstack Architecture + +

+ Perstack is **a containerized harness for agentic apps**. - **Harness = Runtime + Config** — Instructions, agent topology, and tools are defined in TOML — not wired in code. The runtime executes what you declare in config. diff --git a/docs/architecture.svg b/docs/architecture.svg new file mode 100644 index 00000000..2085b592 --- /dev/null +++ b/docs/architecture.svg @@ -0,0 +1,228 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +ARCHITECTURE OF +Perstack + + + + + + + + + + + + + + +EPHEMERAL CONTAINER +perstack/perstack + + + + + +perstack.toml +Expert definitions + + + + + +@perstack/runtime +Agentic loop · Event sourcing + + + + + +stdio + + + + + + + + + + +Workspace +Volume mount + + + + + +Shell +nonroot + sudo + + + + + +MCP servers +@perstack/base and others + + +INPUT + + + + +Query + + + + +Checkpoint + +query + + +resume + + + + + +Env + +env + + + +requiredEnv only + + +EXTERNAL + + + + + +Your application +React · TUI · @perstack/react + +events + + + + + + +LLM providers +Anthropic · OpenAI · Fireworks … + +API + + + + + + +MCP remote +SSE servers (optional) + + +SSE + + + + +SECURITY BOUNDARY: NAMESPACES · CGROUPS + RUNTIME-SPECIFIC ISOLATION + + +Egress filtering ↗ + + + + + + +INFRASTRUCTURE + + +Docker Desktop + + +Cloud Run + + +ECS / Fargate + + +Other container runtimes + + diff --git a/docs/index.mdx b/docs/index.mdx index 99c5a203..1aefc7e1 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -7,6 +7,8 @@ pagefind: true import { LinkCard, CardGrid } from '@astrojs/starlight/components'; +Perstack Architecture + Perstack is a containerized harness for agentic apps. - **Harness = Runtime + Config** — Instructions, agent topology, and tools are defined in TOML — not wired in code. The runtime executes what you declare in config.