create-idocs 0.0.0-stage → 0.3.1

package/template/diagrams/shop/diagram.yaml

@@ -0,0 +1,105 @@
+# yaml-language-server: $schema=../diagram.schema.json
+title: The shop
+description: |
+  A small online shop. **Click any box** to read about it, or pick a scenario above
+  the diagram and press play to watch a request travel through the system.
+
+groups:
+  backend:
+    label: Backend
+    caption: runs on Kubernetes
+
+nodes:
+  browser:
+    kind: client
+    icon: react
+    title: Shopper browser
+    sub: React storefront
+  gateway:
+    kind: gateway
+    icon: nginx
+    title: API gateway
+    sub: ":443"
+    in: backend
+  catalog:
+    kind: service
+    icon: nodejs
+    title: Catalog
+    sub: ":4001 · Node.js"
+    lines: [products and prices]
+    uses: [cache, db]
+    in: backend
+  orders:
+    kind: service
+    icon: lucide:shopping-cart
+    title: Orders
+    sub: ":4002"
+    lines: [creates and tracks orders]
+    uses: [db]
+    in: backend
+  cache:
+    kind: cache
+    icon: redis
+    title: Redis
+    sub: product cache
+    in: backend
+  db:
+    kind: database
+    icon: postgresql
+    title: PostgreSQL
+    sub: products and orders
+    in: backend
+  payments:
+    kind: external
+    icon: stripe
+    title: Stripe
+    sub: payment provider
+
+edges:
+  - browser -> gateway: HTTPS
+  - gateway -> catalog: /products
+  - gateway -> orders: /orders
+  - catalog -> cache: { kind: data, label: lookup }
+  - catalog -> db: { kind: data }
+  - orders -> db: { kind: data }
+  - orders -> payments: { kind: channel, label: charge, auth: API key, payload: payment intent }
+
+scenarios:
+  browse:
+    title: Browse a product
+    summary: The shopper opens a product page. The catalog answers from the cache.
+    steps:
+      - browser -> catalog: GET /products/42
+      - catalog -> cache: { label: GET product:42, kind: lookup }
+      - cache -> catalog: { label: hit, note: A cache hit never touches the database. }
+      - catalog -> browser: 200 OK
+
+  checkout:
+    title: Place an order
+    summary: The order is saved first, charged second, and confirmed last.
+    phases:
+      - title: Save
+        steps:
+          - browser -> orders: POST /orders
+          - orders -> db: { label: INSERT order (pending), kind: lookup }
+      - title: Charge
+        steps:
+          - orders -> payments: create payment intent
+          - at payments:
+              label: authorise card
+              note: Stripe is the one step we do not control.
+          - payments -> orders: succeeded
+      - title: Confirm
+        steps:
+          - orders -> db: { label: mark paid, kind: lookup }
+          - orders -> browser: 201 Created
+
+  declined:
+    title: Card declined
+    summary: Stripe refuses the card. The order stays pending and the shopper is told why.
+    steps:
+      - browser -> orders: POST /orders
+      - orders -> payments: create payment intent
+      - payments -> orders: { label: card_declined, kind: error }
+      - at orders: { label: keep order pending, kind: error }
+      - orders -> browser: { label: 402 Payment Required, kind: error }

package/template/diagrams/shop/nodes/gateway.md

@@ -0,0 +1 @@
+The only public entry point. It checks the user's token and routes each request by path.

package/template/diagrams/shop/nodes/orders.md

@@ -0,0 +1,9 @@
+The orders service owns the order lifecycle.
+
+| State | Meaning |
+|---|---|
+| `pending` | saved, not yet charged |
+| `paid` | the payment went through |
+| `failed` | the card was declined |
+
+This text is `diagrams/shop/nodes/orders.md`. Edit it, and it changes in the drawer that opens when a reader clicks the box.

package/template/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "my-docs",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "check": "idocs check",
+    "idocs": "idocs"
+  },
+  "dependencies": {
+    "@astrojs/react": "^7.0.0",
+    "@astrojs/starlight": "^0.42.0",
+    "@fontsource/ibm-plex-mono": "^5.3.0",
+    "@fontsource/ibm-plex-sans": "^5.3.0",
+    "@the-package-labs/idocs-astro": "^0.3.1",
+    "@the-package-labs/idocs-react": "^0.3.1",
+    "astro": "^7.0.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@the-package-labs/idocs": "^0.3.1",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0"
+  },
+  "packageManager": "pnpm@12.9.1"
+}

package/template/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="7" fill="#0a6f8f"/><circle cx="9" cy="16" r="3" fill="#fff"/><circle cx="23" cy="9" r="3" fill="#fff"/><circle cx="23" cy="23" r="3" fill="#fff"/><path d="M12 16h4l3-7h1M16 16l3 7h1" stroke="#fff" stroke-width="1.6" fill="none" stroke-linecap="round" stroke-linejoin="round"/></svg>

package/template/src/content/docs/architecture.mdx

@@ -0,0 +1,13 @@
+---
+title: How the shop works
+description: The architecture of the example shop, as a diagram you can explore.
+tableOfContents: false
+---
+
+import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'
+
+This page is `src/content/docs/architecture.mdx`. The picture comes from `diagrams/shop/diagram.yaml`.
+
+<Diagram name="shop" showDescription />
+
+Use the page around a diagram for what the diagram cannot say: why a choice was made, what to watch out for, who to ask.

package/template/src/content/docs/editing.mdx

@@ -0,0 +1,62 @@
+---
+title: Editing diagrams
+description: The ten-minute tour of diagram.yaml.
+---
+
+import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'
+
+Every diagram is a folder under `diagrams/`. Save a file and the page reloads.
+
+```sh
+pnpm idocs new payments      # creates diagrams/payments/diagram.yaml
+pnpm check                   # validates every diagram; errors point at file:line:column
+```
+
+Show it on any page:
+
+```mdx
+import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'
+
+<Diagram name="payments" />
+```
+
+## Boxes and arrows
+
+```yaml
+nodes:
+  api: { kind: service, icon: nodejs, title: Orders API, sub: ":4002" }
+  db:  { kind: database, icon: postgresql, title: PostgreSQL }
+
+edges:
+  - api -> db: { kind: data, label: SQL }
+```
+
+`kind` picks a default icon and colour. `icon` takes a name like `postgresql`; find one with `pnpm idocs icons search redis`. Put what a reader should see when they click a box in `diagrams/<name>/nodes/<id>.md`.
+
+## Stories
+
+A scenario is a story that plays over the diagram:
+
+```yaml
+scenarios:
+  load-orders:
+    title: Load my orders
+    steps:
+      - api -> db: { label: SELECT, kind: lookup }
+      - db -> api: rows
+      - at api: { label: build the response, note: Why this step matters. }
+```
+
+Group steps into `phases:` for longer stories, give failures their own scenario, and put long ones in `scenarios/<id>.yaml`.
+
+Every scenario can also be read as a swimlane **story** (the *Story* button above the diagram). Give steps a `title` and a `detail` to write it up, and set `mode: story` on a scenario to open it that way.
+
+## Try one
+
+Here is the shop diagram again. Press play on **Card declined**.
+
+<Diagram name="shop" scenario="declined" />
+
+## Learn the rest
+
+The full format, layout hints, icons and theming are documented at https://github.com/The-Package-Labs/idocs. If you use Claude Code, the `idocs` skill in `.claude/skills/` knows the format: ask it to draw a flow from your code, and it will run `pnpm check` and fix what it reports.

package/template/src/content/docs/index.mdx

@@ -0,0 +1,18 @@
+---
+title: My docs
+description: How our system works, with diagrams you can play.
+template: splash
+hero:
+  tagline: Click a box to read about it. Pick a scenario and press play to watch a request travel through the system.
+  actions:
+    - text: See how the shop works
+      link: architecture/
+      icon: right-arrow
+    - text: Edit these docs
+      link: editing/
+      variant: minimal
+---
+
+import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'
+
+<Diagram name="shop" scenario="checkout" />

package/template/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content'
+import { docsLoader } from '@astrojs/starlight/loaders'
+import { docsSchema } from '@astrojs/starlight/schema'
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+}

package/template/src/env.d.ts

@@ -0,0 +1,2 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="@the-package-labs/idocs-astro/virtual" />

package/template/src/styles/custom.css

@@ -0,0 +1,16 @@
+/* Your theme. Override --idocs-* tokens to restyle every diagram, for example:
+
+   .idocs { --idocs-accent: #7a4ec4; }
+   :root[data-theme='dark'] .idocs { --idocs-accent: #b79bf0; }
+*/
+:root {
+  --sl-color-accent-high: #0a6f8f;
+}
+
+:root[data-theme="light"] {
+  --sl-color-accent: #0a6f8f;
+}
+
+:root[data-theme="dark"] {
+  --sl-color-accent: #55bcdb;
+}

package/template/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "src/**/*"],
+  "exclude": ["dist"],
+  "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "react" }
+}