@itsthecsguy/linework 0.1.1 → 0.1.3

package/skills/linework/SKILL.md

@@ -33,7 +33,14 @@ Never fall back to writing SVG or draw.io XML by hand. Tell the user what failed
    - `er`: database tables, their columns and how they relate.
 
    If the doc already has a Mermaid diagram, convert it instead of rewriting it: `linework import doc.md --block 1 -o docs/diagrams/x.drawio.svg`.
-3. **Write the spec** to `/tmp/spec.yaml`, or pipe it on stdin with `-` as the file. Start from the closest file in `examples/` next to this guide: `checkout.yaml` (architecture), `serverless-aws.yaml` (architecture with AWS icons), `refund-flow.yaml` (flow), `payment-state.yaml` (state), `pay-sequence.yaml` (sequence), `billing-er.yaml` (ER). The `.drawio.svg` is the source of truth, so you don't need to keep the YAML.
+3. **Write the spec** to `/tmp/spec.yaml`, or pipe it on stdin with `-` as the file. Start from the closest file in `examples/` next to this guide:
+   - architecture: `checkout.yaml` (small), `platform.yaml` (clients, nested groups, 17 nodes), `serverless-aws.yaml` (AWS icons), `gcp-ingest.yaml` (GCP icons)
+   - flow: `refund-flow.yaml` (branches), `deploy-flow.yaml` (a retry loop back to an earlier step)
+   - state: `payment-state.yaml`, `job-state.yaml` (pause/resume pairs and a self-transition)
+   - sequence: `pay-sequence.yaml` (alt, note), `auth-seq.yaml` (loop with a nested opt)
+   - ER: `billing-er.yaml` (small), `shop-er.yaml` (7 tables, composite keys)
+
+   The `.drawio.svg` is the source of truth, so you don't need to keep the YAML.
 4. **Build with a preview:**
    ```bash
    linework build /tmp/spec.yaml -o docs/diagrams/checkout.drawio.svg --png /tmp/checkout.png
@@ -78,7 +85,7 @@ edges:                        # "from ARROW to: label"
   - `soft`: borderless pastel cards, tinted by kind. For slides and docs that want color coding.
   - `dark`: for dark-mode docs and slides.
   - `sketch`: hand-drawn lines and handwriting. For early proposals ("this is a draft") and whiteboard-style explainers.
-  - `blueprint`: light lines on deep blue, monospace. For technical deep dives that want a distinct look.
+  - `blueprint`: blue ink on pale drafting paper, monospace. For technical deep dives that want a distinct look.
   - `c4`: C4-model conventions; labels each box with its element type.
 - Color is for meaning, so most nodes stay neutral:
   - `highlight: true` on a node, group or participant, or `==>` on an edge or message, makes it the first thing a reader sees. Highlight the one path or component the surrounding text is about: often one node and the 2 or 3 edges into and out of it. `build` warns when you highlight so much that nothing stands out.

package/skills/linework/examples/auth-seq.yaml

@@ -0,0 +1,35 @@
+type: sequence
+title: OAuth login with refresh
+participants:
+  user:  { label: User, kind: person }
+  app:   { label: SPA, kind: client }
+  bff:   { label: BFF, tech: Node.js }
+  idp:   { label: Identity provider, kind: external }
+  api:   { label: Resource API }
+  cache: { label: Token cache, kind: cache }
+messages:
+  - user -> app: Sign in
+  - app -> bff: GET /login
+  - bff --> app: 302 to /authorize
+  - app -> idp: /authorize?code_challenge=...
+  - idp -> user: Login form
+  - user -> idp: Credentials + MFA
+  - idp --> app: redirect with code
+  - app -> bff: GET /callback?code
+  - bff ==> idp: POST /token (code, verifier)
+  - idp --> bff: access + refresh tokens
+  - bff -> cache: store refresh token
+  - note right of bff: tokens never reach the browser
+  - bff --> app: Set-Cookie session
+  - loop: every API call
+    do:
+      - app -> bff: GET /orders
+      - opt: access token expired
+        do:
+          - bff -> cache: read refresh token
+          - bff -> idp: POST /token (refresh)
+          - idp --> bff: new access token
+      - bff -> api: GET /orders + Bearer
+      - api -> api: validate JWT
+      - api --> bff: 200 orders
+      - bff --> app: orders

package/skills/linework/examples/deploy-flow.yaml

@@ -0,0 +1,32 @@
+type: flow
+title: Deploy pipeline
+nodes:
+  push:    { label: Push to main, kind: terminal }
+  build:   { label: Build and unit test }
+  ok:      { label: Tests pass?, kind: decision }
+  fix:     { label: Notify author, kind: error }
+  stage:   { label: Deploy to staging }
+  smoke:   { label: Run smoke tests against staging }
+  smokeok: { label: Healthy?, kind: decision }
+  canary:  { label: Canary 5% of traffic }
+  metrics: { label: Error rate under 0.1%?, kind: decision }
+  roll:    { label: Roll back canary, kind: error }
+  full:    { label: Promote to 100% }
+  done:    { label: Released, kind: terminal }
+  artifact: { label: Container image, kind: data }
+edges:
+  - push -> build
+  - build -> ok
+  - ok -> fix: "no"
+  - ok -> artifact: "yes"
+  - artifact -> stage
+  - stage -> smoke
+  - smoke -> smokeok
+  - smokeok -> canary: "yes"
+  - smokeok -> roll: "no"
+  - canary -> metrics
+  - metrics -> full: "yes"
+  - metrics -> roll: "no"
+  - roll -> fix
+  - fix -> build: retry after fix
+  - full -> done

package/skills/linework/examples/gcp-ingest.yaml

@@ -0,0 +1,21 @@
+type: architecture
+title: Ingest pipeline on GCP
+groups:
+  gcp: { label: Google Cloud project }
+nodes:
+  devices: { label: Sensors, kind: client, tech: MQTT }
+  lb:      { label: Load balancer, icon: gcp.cloud_load_balancing, in: gcp }
+  run:     { label: Ingest API, icon: gcp.cloud_run, tech: Cloud Run, in: gcp }
+  ps:      { label: telemetry, kind: queue, icon: gcp.pubsub, tech: Pub/Sub, in: gcp }
+  df:      { label: Stream job, icon: gcp.dataflow, tech: Dataflow, in: gcp }
+  bq:      { label: Warehouse, kind: database, icon: gcp.bigquery, tech: BigQuery, in: gcp }
+  gcs:     { label: Raw archive, kind: storage, icon: gcp.cloud_storage, tech: GCS, in: gcp }
+  looker:  { label: Looker, kind: external, tech: Dashboards }
+edges:
+  - devices -> lb: HTTPS
+  - lb -> run
+  - run -.-> ps: publish
+  - ps -.-> df: subscribe
+  - df -> bq: stream insert
+  - df -> gcs: write Avro
+  - looker -> bq: SQL

package/skills/linework/examples/job-state.yaml

@@ -0,0 +1,25 @@
+type: state
+title: Background job
+nodes:
+  queued:    {}
+  running:   {}
+  paused:    {}
+  retrying:  { label: Waiting to retry }
+  succeeded: { kind: success }
+  failed:    { kind: error }
+  cancelled: {}
+edges:
+  - "[*] -> queued"
+  - queued -> running: worker picks up
+  - running -> succeeded: exit 0
+  - running -> retrying: error, attempts < 5
+  - retrying -> queued: backoff elapsed
+  - running -> failed: error, attempts = 5
+  - running -> paused: pause
+  - paused -> running: resume
+  - queued -> cancelled: cancel
+  - paused -> cancelled: cancel
+  - running -> running: heartbeat
+  - "succeeded -> [*]"
+  - "failed -> [*]"
+  - "cancelled -> [*]"

package/skills/linework/examples/platform.yaml

@@ -0,0 +1,45 @@
+type: architecture
+title: Platform
+groups:
+  edge: { label: Edge }
+  cluster: { label: Kubernetes cluster }
+  core: { label: Core services, in: cluster }
+  data: { label: Data tier }
+nodes:
+  user:    { label: Customer, kind: person }
+  admin:   { label: Support agent, kind: person }
+  mobile:  { label: Mobile app, kind: client, tech: Swift }
+  web:     { label: Web dashboard, kind: client, tech: React }
+  cdn:     { label: CDN, kind: cache, tech: CloudFront, in: edge }
+  gw:      { label: API gateway, tech: Kong, in: edge }
+  auth:    { label: Auth service, tech: Go, in: core }
+  orders:  { label: Orders service, tech: Kotlin, in: core, highlight: true }
+  search:  { label: Search service, tech: Rust, in: core }
+  notify:  { label: Notification worker, kind: function, tech: Node.js, in: cluster }
+  bus:     { label: domain-events, kind: queue, tech: Kafka, in: cluster }
+  pg:      { label: Orders DB, kind: database, tech: Postgres 16, in: data }
+  es:      { label: Search index, kind: database, tech: OpenSearch, in: data }
+  redis:   { label: Session store, kind: cache, tech: Redis, in: data }
+  s3:      { label: Media bucket, kind: storage, tech: S3, in: data }
+  twilio:  { label: Twilio, kind: external, tech: SMS }
+  idp:     { label: Okta, kind: external, tech: OIDC }
+edges:
+  - user -> mobile
+  - user -> web
+  - admin -> web
+  - mobile -> cdn: assets
+  - web -> cdn: assets
+  - mobile ==> gw: HTTPS
+  - web ==> gw: HTTPS
+  - cdn -> s3: origin fetch
+  - gw -> auth: verify token
+  - auth -> idp: OIDC
+  - auth -> redis: sessions
+  - gw ==> orders: gRPC
+  - gw -> search: gRPC
+  - orders ==> pg: SQL
+  - orders -.-> bus: OrderPlaced
+  - bus -.-> search: reindex
+  - bus -.-> notify: consume
+  - search -> es: query
+  - notify -> twilio: send SMS

package/skills/linework/examples/shop-er.yaml

@@ -0,0 +1,26 @@
+type: er
+title: Storefront schema
+nodes:
+  customers:
+    fields: [id: uuid pk, email: text unique, name: text, created_at: timestamptz]
+  addresses:
+    fields: [id: uuid pk, customer_id: uuid fk, line1: text, city: text, country: char(2)]
+  orders:
+    fields: [id: uuid pk, customer_id: uuid fk, shipping_address_id: uuid fk, status: order_status, total_cents: bigint, placed_at: timestamptz null]
+  order_items:
+    fields: [order_id: uuid pk fk, product_id: uuid pk fk, quantity: int, unit_price_cents: bigint]
+  products:
+    fields: [id: uuid pk, sku: text unique, title: text, price_cents: bigint]
+  inventory:
+    fields: [product_id: uuid pk fk, warehouse: text pk, on_hand: int]
+  payments:
+    kind: external
+    fields: [id: text pk, order_id: uuid fk, provider: text]
+edges:
+  - addresses }o--|| customers: has
+  - orders }o--|| customers: placed by
+  - orders }o--|| addresses: ships to
+  - order_items }|--|| orders: contains
+  - order_items }o--|| products: of
+  - inventory }o--|| products: stocks
+  - payments |o..|| orders: pays

package/skills/linework/references/spec.md

@@ -40,9 +40,9 @@ nodes:
 | `clean` | white boxes with hairline borders, groups drawn as gray grounds, cobalt accent. Nodes are neutral unless the kind means something (error, success). | IBM Plex Sans |
 | `soft` | borderless pastel cards, each kind its own tint | IBM Plex Sans |
 | `dark` | `clean` in GitHub's dark colors, so it sits flush on a dark README | IBM Plex Sans |
-| `sketch` | hand-drawn strokes, pastel fills, red accent | Kalam (handwriting) |
-| `blueprint` | light lines on deep blue, yellow accent, drafting capitals for group titles | IBM Plex Mono |
-| `c4` | C4-PlantUML colors; each box says its element type | IBM Plex Sans |
+| `sketch` | hand-drawn strokes, pastel fills, blue accent | Kalam (handwriting) |
+| `blueprint` | blue ink on pale drafting paper, drafting capitals for group titles | IBM Plex Mono |
+| `c4` | C4's colors (dark person, blue containers, gray external systems) in quiet tones; each box says its element type | IBM Plex Sans |
 
 The "drawn as" columns below describe `soft`. In `clean`, `dark` and `blueprint`, kinds differ by shape and dash only, and color comes from `highlight`, `color` and the error/success kinds.
 

package/skills/linework/references/style-guide.md

@@ -38,9 +38,17 @@ Linework handles the layout and the look. These rules are about content, which i
 - **Keep error and success kinds for real errors and successes.** They're red and green in every style.
 - **Pick the style for the medium**: `clean` for docs and READMEs, `dark` for dark-mode pages, `soft` for slides, `sketch` for early drafts, `blueprint` for technical deep dives. Use one style across all the diagrams in a doc.
 
+## Order
+
+Layout reads the spec top to bottom, so the order you write things in shows up in the picture.
+
+- **List nodes and edges in reading order**: the entry point first, then each step as the request or flow reaches it. A flow's main path then runs straight down, and an edge back to an earlier node (a retry, a resume) is drawn as the loop it is.
+- **Write a reply after its call** (`api -> stripe`, then `stripe -.-> api`). The pair is drawn side by side.
+- **In ER, name foreign keys after the table they point at**: `customer_id` for `customers`, `shipping_address_id` for `addresses`. The relationship line then attaches to that row and to the other table's primary key. A key named anything else attaches to the table as a whole.
+
 ## Direction
 
-- Leave out `direction` on the first build. `auto` tries both and keeps the one that fits a doc page, which is about 800px wide.
+- Leave out `direction` on the first build. `auto` tries both and keeps the one that fits a doc page, which is about 800px wide. ER diagrams always run left to right, since relationships attach to the sides of the key rows.
 - Set it only after looking at the result, and only if it reads wrong. A short linear pipeline of 5 or fewer steps can read better as LR.
 - Don't force LR on a diagram with more than about 6 nodes in a row. It comes out 1,500px or more wide, and embedded in a doc its text shrinks to unreadable. `check` warns about this as `too-wide`.