#!/usr/bin/env python3
"""Emit architecture SVGs for the Verae Time x Zapier getting-started guide."""

from __future__ import annotations

from pathlib import Path

OUT = Path(__file__).resolve().parents[1] / "docs" / "diagrams"
OUT.mkdir(parents=True, exist_ok=True)

# Palette matches getting-started.pdf
NAVY = "#0F2744"
TEAL = "#1A6B6B"
TEAL_DK = "#134848"
SLATE = "#334155"
MUTED = "#64748B"
LINE = "#94A3B8"
PAPER = "#FFFFFF"
BG = "#F8FAFC"
PUBLIC = "#E8F1F8"
PRIVATE = "#F3EDE0"
VERAE = "#E8F6EE"
ZAPIER = "#FFF1E6"
ACCENT = "#C2410C"
OK = "#15803D"
WARN = "#B45309"


class Svg:
    def __init__(self, w: int, h: int, title: str):
        self.w = w
        self.h = h
        self.title = title
        self.parts: list[str] = []

    def raw(self, s: str) -> None:
        self.parts.append(s)

    def rect(
        self,
        x,
        y,
        w,
        h,
        fill=PAPER,
        stroke=NAVY,
        sw=1.4,
        r=8,
        opacity=1,
    ) -> None:
        self.raw(
            f'<rect x="{x}" y="{y}" width="{w}" height="{h}" rx="{r}" '
            f'fill="{fill}" fill-opacity="{opacity}" stroke="{stroke}" '
            f'stroke-width="{sw}"/>'
        )

    def text(
        self,
        x,
        y,
        s,
        size=12,
        fill=NAVY,
        anchor="start",
        weight="500",
        family="Helvetica, Arial, sans-serif",
    ) -> None:
        esc = (
            s.replace("&", "&amp;")
            .replace("<", "&lt;")
            .replace(">", "&gt;")
        )
        self.raw(
            f'<text x="{x}" y="{y}" font-family="{family}" font-size="{size}" '
            f'font-weight="{weight}" fill="{fill}" text-anchor="{anchor}">{esc}</text>'
        )

    def lines(self, x, y, lines, size=11, fill=SLATE, anchor="start", leading=14, weight="400"):
        for i, line in enumerate(lines):
            self.text(x, y + i * leading, line, size=size, fill=fill, anchor=anchor, weight=weight)

    def arrow(self, x1, y1, x2, y2, color=TEAL, sw=1.8, label="", label_off=-10) -> None:
        self.raw(
            f'<line x1="{x1}" y1="{y1}" x2="{x2}" y2="{y2}" stroke="{color}" '
            f'stroke-width="{sw}" marker-end="url(#arrow)"/>'
        )
        if label:
            mx, my = (x1 + x2) / 2, (y1 + y2) / 2 + label_off
            self.text(mx, my, label, size=10, fill=TEAL_DK, anchor="middle", weight="600")

    def varrow(self, x, y1, y2, color=TEAL, sw=1.8, label="", lx=8) -> None:
        self.arrow(x, y1, x, y2, color=color, sw=sw)
        if label:
            self.text(x + lx, (y1 + y2) / 2 + 4, label, size=10, fill=TEAL_DK, weight="600")

    def harrow(self, x1, x2, y, color=TEAL, sw=1.8, label="", label_off=-11) -> None:
        self.arrow(x1, y, x2, y, color=color, sw=sw, label=label, label_off=label_off)

    def badge(self, x, y, w, h, text, fill=TEAL, color=PAPER) -> None:
        self.rect(x, y, w, h, fill=fill, stroke=fill, r=4, sw=0)
        self.text(x + w / 2, y + h / 2 + 4, text, size=10, fill=color, anchor="middle", weight="700")

    def save(self, name: str) -> Path:
        path = OUT / name
        body = "\n  ".join(self.parts)
        svg = f"""<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="{self.w}" height="{self.h}"
     viewBox="0 0 {self.w} {self.h}" role="img" aria-label="{self.title}">
  <title>{self.title}</title>
  <defs>
    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
            markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 z" fill="{TEAL}"/>
    </marker>
    <marker id="arrow-navy" viewBox="0 0 10 10" refX="9" refY="5"
            markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 z" fill="{NAVY}"/>
    </marker>
    <marker id="arrow-accent" viewBox="0 0 10 10" refX="9" refY="5"
            markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 z" fill="{ACCENT}"/>
    </marker>
  </defs>
  <rect width="100%" height="100%" fill="{BG}"/>
  {body}
</svg>
"""
        path.write_text(svg, encoding="utf-8")
        print(f"wrote {path.relative_to(OUT.parent.parent)} ({path.stat().st_size} bytes)")
        return path


def high_level():
    s = Svg(1100, 680, "High-level architecture: Zapier to Verae via middleware")
    s.text(24, 28, "HIGH-LEVEL ARCHITECTURE", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "Verae Time  x  Zapier", size=20, fill=NAVY, weight="700")
    s.text(
        24,
        70,
        "Zapier never calls api.veraetime.net and never speaks NATS. HTTPS only at the public edge.",
        size=12,
        fill=MUTED,
    )

    # Zones
    s.rect(20, 90, 1060, 150, fill=ZAPIER, stroke="#F0D2B8", sw=1.2, r=12)
    s.text(36, 112, "PUBLIC  ·  Zapier cloud", size=11, fill=ACCENT, weight="700")

    s.rect(20, 258, 700, 280, fill=PUBLIC, stroke="#C5D6E8", sw=1.2, r=12)
    s.text(36, 280, "YOUR INFRASTRUCTURE  ·  public HTTPS edge + private workers", size=11, fill=TEAL, weight="700")

    s.rect(740, 258, 340, 280, fill=PRIVATE, stroke="#E0D2B4", sw=1.2, r=12)
    s.text(756, 280, "PRIVATE NETWORK", size=11, fill=WARN, weight="700")

    s.rect(20, 556, 700, 104, fill=VERAE, stroke="#B7DCC7", sw=1.2, r=12)
    s.text(36, 578, "VERAE TIMESTAMPING SERVICE", size=11, fill=OK, weight="700")

    s.rect(740, 556, 340, 104, fill=ZAPIER, stroke="#F0D2B8", sw=1.2, r=12)
    s.text(756, 578, "ZAPIER REST HOOKS", size=11, fill=ACCENT, weight="700")

    # User
    s.rect(40, 128, 150, 88, fill=PAPER, stroke=NAVY)
    s.text(115, 158, "User", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(115, 178, ["Zap editor", "connection form"], size=11, fill=SLATE, anchor="middle")

    # Zapier app
    s.rect(250, 122, 360, 100, fill=PAPER, stroke=NAVY, sw=1.8)
    s.text(430, 148, "Zapier Platform CLI app", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(
        430,
        168,
        ["scratch/veraetime  (session TS)  or  verae-zapier  (zmw_ JS)", "runs on Zapier cloud when a Zap step executes"],
        size=11,
        fill=SLATE,
        anchor="middle",
        leading=15,
    )

    s.rect(660, 128, 180, 88, fill=PAPER, stroke=LINE)
    s.text(750, 158, "Zap trigger", size=13, fill=NAVY, anchor="middle", weight="700")
    s.lines(750, 178, ["Timestamp Completed", "hooks.zapier.com"], size=11, fill=SLATE, anchor="middle")

    s.harrow(190, 250, 172, label="configure / run")
    s.harrow(610, 660, 172, label="hook fires Zap")

    # Middleware
    s.rect(48, 300, 644, 120, fill=PAPER, stroke=NAVY, sw=1.8)
    s.text(370, 326, "verae-zapier-middleware   /zapier/v1/*", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(
        370,
        348,
        [
            "Auth bridge  ·  tenants  ·  entitlements  ·  rate limits  ·  REST Hook store",
            "GET /health   POST /auth/login   GET /auth/me   POST /timestamp[/wait|/batch]",
            "POST /verify   GET /status/{jobId}   POST/DELETE /webhooks/*",
        ],
        size=11,
        fill=SLATE,
        anchor="middle",
        leading=16,
    )

    s.varrow(430, 222, 300, label="HTTPS  Bearer zmw_ / zmt_")

    # NATS
    s.rect(760, 300, 300, 92, fill=PAPER, stroke=NAVY, sw=1.8)
    s.text(910, 328, "NATS JetStream", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(
        910,
        348,
        ["ZAPIER_JOBS  ·  EVENTS  ·  WEBHOOKS", "never on the public internet"],
        size=11,
        fill=SLATE,
        anchor="middle",
    )

    s.harrow(692, 760, 346, label="publish (private)")

    # Workers
    s.rect(760, 412, 300, 108, fill=PAPER, stroke=NAVY)
    s.text(910, 438, "Workers", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(
        910,
        458,
        ["job-poller   jobs.watch", "event-router  jobs.events", "webhook-deliver  webhooks.deliver"],
        size=11,
        fill=SLATE,
        anchor="middle",
        leading=15,
    )
    s.varrow(910, 392, 412)

    # Verae
    s.rect(48, 596, 644, 50, fill=PAPER, stroke=NAVY, sw=1.8)
    s.text(370, 616, "api.veraetime.net", size=12, fill=NAVY, anchor="middle", weight="700")
    s.text(
        370,
        634,
        "POST /auth/login   POST /api/timestamp 202 {jobId}   GET /api/status/{jobId}   POST /api/verify",
        size=11,
        fill=SLATE,
        anchor="middle",
    )
    s.varrow(220, 420, 596, label="sync HTTPS")
    s.arrow(820, 520, 370, 596, label="poll / create")

    # Hooks
    s.rect(760, 596, 300, 50, fill=PAPER, stroke=NAVY)
    s.text(910, 626, "POST hooks.zapier.com  timestamp.completed", size=11, fill=NAVY, anchor="middle", weight="600")
    s.varrow(910, 520, 596, color=ACCENT, label="HTTPS egress")
    return s.save("01-high-level-architecture.svg")


def security():
    s = Svg(1100, 520, "Security boundaries")
    s.text(24, 28, "SECURITY BOUNDARIES", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "What is public, what stays private", size=20, fill=NAVY, weight="700")

    s.rect(20, 80, 1060, 200, fill=ZAPIER, stroke="#F0D2B8", r=12)
    s.text(40, 106, "PUBLIC INTERNET", size=13, fill=ACCENT, weight="700")
    s.rect(48, 124, 300, 130, fill=PAPER, stroke=NAVY)
    s.text(198, 158, "Zapier cloud", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(198, 180, ["CLI app performs", "z.request only", "no NATS, no Verae JWT"], size=12, fill=SLATE, anchor="middle")

    s.rect(400, 124, 300, 130, fill=PAPER, stroke=NAVY, sw=1.8)
    s.text(550, 158, "Middleware HTTPS", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(550, 180, ["/zapier/v1 only", "TLS required in prod", "rate limit + entitlements"], size=12, fill=SLATE, anchor="middle")

    s.rect(752, 124, 300, 130, fill=PAPER, stroke=NAVY)
    s.text(902, 158, "Zapier hook URLs", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(902, 180, ["untrusted egress", "timeouts required", "SSRF allowlist = Phase 15"], size=12, fill=SLATE, anchor="middle")

    s.harrow(348, 400, 189, label="HTTPS in")
    s.harrow(700, 752, 189, label="HTTPS out")

    s.rect(20, 300, 1060, 196, fill=PRIVATE, stroke="#E0D2B4", r=12)
    s.text(40, 326, "PRIVATE  ·  do not expose ports 4222 / store / TOKEN_SECRET", size=13, fill=WARN, weight="700")

    s.rect(48, 348, 320, 126, fill=PAPER, stroke=NAVY)
    s.text(208, 380, "NATS JetStream", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(208, 402, ["tokenRef, not raw JWT", "private network + auth", "mTLS is Phase 15"], size=12, fill=SLATE, anchor="middle")

    s.rect(400, 348, 320, 126, fill=PAPER, stroke=NAVY)
    s.text(560, 380, "Workers + file store", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(560, 402, ["STORE_PATH store.json", "single-node MVP", "Postgres/Redis = Phase 15"], size=12, fill=SLATE, anchor="middle")

    s.rect(752, 348, 300, 126, fill=PAPER, stroke=NAVY)
    s.text(902, 380, "api.veraetime.net", size=14, fill=NAVY, anchor="middle", weight="700")
    s.lines(902, 402, ["Verae JWT stays here", "server-side login only", "MOCK_VERAE for tests"], size=12, fill=SLATE, anchor="middle")

    s.harrow(368, 400, 411)
    s.harrow(720, 752, 411)
    return s.save("02-security-boundaries.svg")


def auth():
    s = Svg(1100, 560, "Two-hop authentication")
    s.text(24, 28, "AUTHENTICATION", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "Two hops  ·  Zapier never sees the Verae JWT", size=20, fill=NAVY, weight="700")

    # Hop 1
    s.rect(20, 80, 1060, 220, fill=PUBLIC, stroke="#C5D6E8", r=12)
    s.text(40, 106, "HOP 1  ·  end user  →  middleware", size=13, fill=TEAL, weight="700")

    s.rect(48, 126, 220, 148, fill=PAPER, stroke=NAVY)
    s.text(158, 156, "User in Zapier", size=13, fill=NAVY, anchor="middle", weight="700")
    s.lines(
        158,
        178,
        ["username + password", "or zmw_ API key", "api_base_url", "default :3100"],
        size=12,
        fill=SLATE,
        anchor="middle",
    )

    s.rect(320, 126, 280, 148, fill=PAPER, stroke=NAVY, sw=1.8)
    s.text(460, 156, "POST /zapier/v1/auth/login", size=13, fill=NAVY, anchor="middle", weight="700")
    s.lines(
        460,
        178,
        ["loginWithCredentials", "or loginWithApiKey", "returns accessToken", "stored as sessionKey (TS)"],
        size=12,
        fill=SLATE,
        anchor="middle",
    )

    s.rect(650, 126, 200, 148, fill=PAPER, stroke=NAVY)
    s.text(750, 156, "Tokens issued", size=13, fill=NAVY, anchor="middle", weight="700")
    s.lines(750, 178, ["zmw_  tenant API key", "zmt_  HMAC session", "TOKEN_SECRET", "never commit"], size=12, fill=SLATE, anchor="middle")

    s.rect(880, 126, 176, 148, fill=PAPER, stroke=NAVY)
    s.text(968, 156, "Auth test", size=13, fill=NAVY, anchor="middle", weight="700")
    s.lines(968, 178, ["GET /auth/me", "tenant + plan", "usage", "401 → refresh"], size=12, fill=SLATE, anchor="middle")

    s.harrow(268, 320, 200)
    s.harrow(600, 650, 200)
    s.harrow(850, 880, 200)

    # Hop 2
    s.rect(20, 320, 1060, 216, fill=VERAE, stroke="#B7DCC7", r=12)
    s.text(40, 346, "HOP 2  ·  middleware  →  Verae  (server-side only)", size=13, fill=OK, weight="700")

    s.rect(48, 366, 300, 148, fill=PAPER, stroke=NAVY)
    s.text(198, 396, "veraeClient", size=13, fill=NAVY, anchor="middle", weight="700")
    s.lines(
        198,
        418,
        ["POST /auth/login on Verae", "or MOCK_VERAE=true", "JWT held in process", "redacted in DEBUG_VERAE"],
        size=12,
        fill=SLATE,
        anchor="middle",
    )

    s.rect(400, 366, 300, 148, fill=PAPER, stroke=NAVY, sw=1.8)
    s.text(550, 396, "api.veraetime.net", size=13, fill=NAVY, anchor="middle", weight="700")
    s.lines(
        550,
        418,
        ["Authorization: Bearer <JWT>", "timestamp / status / verify", "source of truth", "not reachable from Zapier"],
        size=12,
        fill=SLATE,
        anchor="middle",
    )

    s.rect(752, 366, 300, 148, fill=PAPER, stroke=ACCENT, sw=1.8)
    s.text(902, 396, "Do not leak", size=13, fill=ACCENT, anchor="middle", weight="700")
    s.lines(
        902,
        418,
        ["no Verae JWT in Zapier", "no JWT in NATS (use tokenRef)", "no secrets in git", "no secrets in debug logs"],
        size=12,
        fill=SLATE,
        anchor="middle",
    )

    s.harrow(348, 400, 440)
    s.harrow(700, 752, 440)
    return s.save("03-auth-two-hop.svg")


def flow_async():
    s = Svg(1100, 620, "Create Timestamp async plus REST Hook")
    s.text(24, 28, "FLOW A", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "Create Timestamp  ·  async job + hook", size=20, fill=NAVY, weight="700")

    cols = [
        (70, "Zapier app"),
        (290, "Middleware"),
        (510, "NATS"),
        (730, "Workers"),
        (950, "Verae / Hooks"),
    ]
    for x, name in cols:
        s.rect(x - 80, 78, 160, 36, fill=NAVY, stroke=NAVY, r=6)
        s.text(x, 101, name, size=12, fill=PAPER, anchor="middle", weight="700")
        s.raw(f'<line x1="{x}" y1="114" x2="{x}" y2="590" stroke="{LINE}" stroke-dasharray="3 5"/>')

    s.harrow(70, 290, 148, label="1  POST /timestamp")
    s.harrow(290, 950, 190, label="2  entitlement + POST /api/timestamp")
    s.harrow(950, 290, 232, label="3  202 { jobId }", label_off=14)
    s.harrow(290, 70, 274, label="4  return jobId to Zap", label_off=14)
    s.harrow(290, 510, 322, label="5  publish jobs.watch")
    s.harrow(510, 730, 364, label="6  job-poller")
    s.harrow(730, 950, 406, label="7  GET /api/status/{jobId}")
    s.harrow(950, 730, 448, label="8  pending: Nak + delay", label_off=14)
    s.harrow(730, 510, 490, label="9  terminal → jobs.events", label_off=14)
    s.harrow(510, 730, 532, label="10 match webhooks")
    s.harrow(730, 950, 574, label="11 POST timestamp.completed")

    s.text(
        24,
        612,
        "Pair this action with the Timestamp Completed hook trigger. Zapier does not poll Verae.",
        size=11,
        fill=MUTED,
    )
    return s.save("04-flow-async-timestamp.svg")


def flow_wait():
    s = Svg(1100, 480, "Create Timestamp and Wait")
    s.text(24, 28, "FLOW B", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "Create Timestamp and Wait", size=20, fill=NAVY, weight="700")
    s.text(24, 72, "In-process path is live today. Wait-via-NATS is Phase 9.", size=12, fill=MUTED)

    s.rect(40, 100, 200, 80, fill=PAPER, stroke=NAVY)
    s.text(140, 132, "Zapier", size=13, fill=NAVY, anchor="middle", weight="700")
    s.lines(140, 152, ["POST /timestamp/wait"], size=11, fill=SLATE, anchor="middle")

    s.rect(320, 100, 260, 80, fill=PAPER, stroke=NAVY, sw=1.8)
    s.text(450, 132, "Middleware", size=13, fill=NAVY, anchor="middle", weight="700")
    s.lines(450, 152, ["create job, then wait"], size=11, fill=SLATE, anchor="middle")

    s.harrow(240, 320, 140, label="HTTPS")

    # fork
    s.rect(320, 230, 260, 100, fill=PUBLIC, stroke=TEAL)
    s.text(450, 260, "NATS_ENABLED=false", size=12, fill=TEAL, anchor="middle", weight="700")
    s.lines(450, 280, ["in-process poller (Phase 6)", "returns StatusResponse"], size=11, fill=SLATE, anchor="middle")

    s.rect(640, 230, 400, 100, fill=PRIVATE, stroke=WARN)
    s.text(840, 260, "NATS_ENABLED=true  ·  Phase 9 (open)", size=12, fill=WARN, anchor="middle", weight="700")
    s.lines(
        840,
        280,
        ["subscribe to jobs.events", "hard timeout → { jobId, status: pending }"],
        size=11,
        fill=SLATE,
        anchor="middle",
    )

    s.varrow(450, 180, 230)
    s.arrow(580, 180, 840, 230)

    s.rect(40, 380, 1020, 72, fill=VERAE, stroke="#B7DCC7")
    s.text(550, 410, "Return to Zapier", size=13, fill=NAVY, anchor="middle", weight="700")
    s.lines(
        550,
        430,
        ["completed / failed status object   or   pending + jobId on timeout (Zapier can Find Job Status next)"],
        size=11,
        fill=SLATE,
        anchor="middle",
    )
    s.varrow(450, 330, 380)
    s.varrow(840, 330, 380)
    return s.save("05-flow-wait.svg")


def nats():
    s = Svg(1100, 560, "NATS subject topology")
    s.text(24, 28, "NATS + JETSTREAM", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "Private subjects, streams, and workers", size=20, fill=NAVY, weight="700")

    streams = [
        (40, "ZAPIER_JOBS", "verae.zapier.jobs.watch", "Work queue", "job-poller", "GET /api/status/{jobId}"),
        (310, "ZAPIER_EVENTS", "verae.zapier.jobs.events", "Limits (time)", "event-router", "enqueue webhooks / waiters"),
        (580, "ZAPIER_WEBHOOKS", "verae.zapier.webhooks.deliver", "Work queue", "webhook-deliver", "POST Zapier targetUrl"),
        (850, "ZAPIER_USAGE", "verae.zapier.usage", "Optional", "usage-writer", "billing export"),
    ]
    for x, stream, subj, ret, cons, call in streams:
        s.rect(x, 88, 250, 250, fill=PAPER, stroke=NAVY, r=10)
        s.badge(x + 14, 104, 222, 26, stream)
        s.text(x + 125, 156, subj, size=11, fill=TEAL_DK, anchor="middle", weight="600")
        s.lines(
            x + 125,
            182,
            [ret, "", "consumer: " + cons, call],
            size=12,
            fill=SLATE,
            anchor="middle",
            leading=18,
        )

    s.harrow(290, 310, 213)
    s.harrow(560, 580, 213)
    s.harrow(830, 850, 213, color=LINE)

    s.rect(40, 364, 1020, 168, fill=PRIVATE, stroke="#E0D2B4", r=10)
    s.text(60, 392, "Ack semantics", size=13, fill=NAVY, weight="700")
    s.lines(
        60,
        418,
        [
            "Job still pending          Nak with delay ~ intervalMs   or republish attempt+1",
            "Job terminal               publish jobs.events, then Ack the watch message",
            "Webhook HTTP 2xx           Ack     ·     5xx / network  Nak until max_deliver",
            "Poison message             terminate after max_deliver; DEBUG_VERAE=webhooks DLQ log",
            "Prefer tokenRef over embedding a Verae JWT in any NATS payload",
        ],
        size=12,
        fill=SLATE,
        leading=22,
    )
    return s.save("06-nats-topology.svg")


def operations():
    s = Svg(1100, 640, "Zapier operations mapped to middleware and Verae")
    s.text(24, 28, "OPERATIONS MAP", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "Connector  →  /zapier/v1  →  Verae wrap", size=20, fill=NAVY, weight="700")

    headers = [(40, "Zapier"), (280, "Type"), (400, "Middleware"), (700, "Verae")]
    s.rect(20, 78, 1060, 36, fill=NAVY, stroke=NAVY, r=0)
    for x, h in headers:
        s.text(x, 101, h, size=12, fill=PAPER, weight="700")

    rows = [
        ("Create Timestamp", "create", "POST /timestamp", "POST /api/timestamp  →  202 jobId"),
        ("Create Timestamp and Wait", "create", "POST /timestamp/wait", "create + poll / wait"),
        ("Create Batch Timestamps", "create", "POST /timestamp/batch", "POST /api/batch/timestamp"),
        ("Verify Certificate", "create", "POST /verify", "POST /api/verify"),
        ("Find Job Status", "search", "GET /status/{jobId}", "GET /api/status/{jobId}"),
        ("Find Job Verification", "search (TS)", "GET /status/{jobId}/verification", "GET /api/verify/{jobId}"),
        ("Timestamp Completed", "hook", "POST /webhooks/subscribe", "(no Verae hook — middleware stores targetUrl)"),
    ]
    y = 114
    for i, (a, b, c, d) in enumerate(rows):
        fill = PAPER if i % 2 == 0 else "#EEF2F6"
        s.rect(20, y, 1060, 52, fill=fill, stroke=LINE, r=0, sw=0.6)
        s.text(40, y + 32, a, size=13, fill=NAVY, weight="600")
        s.text(280, y + 32, b, size=12, fill=SLATE)
        s.text(400, y + 32, c, size=12, fill=TEAL_DK, weight="600")
        s.text(700, y + 32, d, size=12, fill=SLATE)
        y += 52

    s.text(
        24,
        500,
        "Creates return one object. Searches and hook perform return arrays. 404 on status search → [].",
        size=12,
        fill=MUTED,
    )

    s.rect(20, 520, 340, 96, fill=ZAPIER, stroke="#F0D2B8")
    s.text(36, 546, "Zapier cloud", size=12, fill=ACCENT, weight="700")
    s.lines(36, 566, ["scratch/veraetime", "or verae-zapier"], size=12, fill=SLATE)

    s.rect(390, 520, 340, 96, fill=PUBLIC, stroke="#C5D6E8")
    s.text(406, 546, "Middleware  :3100", size=12, fill=TEAL, weight="700")
    s.lines(406, 566, ["api_base_url / MIDDLEWARE_BASE_URL", "never api.veraetime.net from Zapier"], size=12, fill=SLATE)

    s.rect(760, 520, 320, 96, fill=VERAE, stroke="#B7DCC7")
    s.text(776, 546, "Verae API", size=12, fill=OK, weight="700")
    s.lines(776, 566, ["JWT server-side only", "OpenAPI in scratch/our-api/"], size=12, fill=SLATE)

    s.harrow(360, 390, 568)
    s.harrow(730, 760, 568)
    return s.save("07-operations-map.svg")


def middleware():
    s = Svg(1100, 580, "Middleware internals")
    s.text(24, 28, "MIDDLEWARE INTERNALS", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "verae-zapier-api/verae-zapier-middleware", size=20, fill=NAVY, weight="700")

    s.rect(20, 80, 160, 70, fill=PAPER, stroke=NAVY)
    s.text(100, 110, "GET /health", size=12, fill=NAVY, anchor="middle", weight="700")
    s.lines(100, 128, ["liveness"], size=11, fill=SLATE, anchor="middle")

    s.rect(200, 80, 880, 70, fill=NAVY, stroke=NAVY)
    s.text(640, 110, "Express  /zapier   →   /v1", size=16, fill=PAPER, anchor="middle", weight="700")
    s.lines(640, 132, ["authenticate  ·  rateLimit on protected routes"], size=12, fill="#CBD5E1", anchor="middle")

    # public
    s.rect(20, 172, 340, 180, fill=PUBLIC, stroke="#C5D6E8")
    s.text(36, 198, "Public", size=13, fill=TEAL, weight="700")
    s.lines(
        36,
        222,
        [
            "POST /v1/auth/login",
            "GET  /v1/auth/me",
            "POST /v1/signup",
            "GET  /v1/admin/*  (X-Admin-Secret)",
        ],
        size=13,
        fill=SLATE,
        leading=26,
    )

    s.rect(380, 172, 360, 180, fill=PAPER, stroke=NAVY, sw=1.8)
    s.text(396, 198, "Protected  /v1", size=13, fill=NAVY, weight="700")
    s.lines(
        396,
        222,
        [
            "/timestamp   /timestamp/wait   /batch",
            "/verify",
            "/status/:jobId[/verification]",
            "/webhooks/subscribe|unsubscribe",
        ],
        size=13,
        fill=SLATE,
        leading=26,
    )

    s.rect(760, 172, 320, 180, fill=PRIVATE, stroke="#E0D2B4")
    s.text(776, 198, "Services + store", size=13, fill=WARN, weight="700")
    s.lines(
        776,
        222,
        [
            "auth / entitlement / tenant",
            "timestamp / verify / webhook",
            "store.json  tenants usage hooks",
            "veraeClient  (+ mock)",
        ],
        size=13,
        fill=SLATE,
        leading=26,
    )

    s.rect(20, 372, 520, 180, fill=PAPER, stroke=NAVY)
    s.text(36, 400, "Flags", size=13, fill=NAVY, weight="700")
    s.lines(
        36,
        426,
        [
            "NATS_ENABLED=false   in-process job poller (Phase 6 product path)",
            "NATS_ENABLED=true    JetStream workers; no in-process poller",
            "MOCK_VERAE=true      deterministic jobs, no live Verae",
            "DEBUG_VERAE=auth,nats,jobs,webhooks,http,billing",
        ],
        size=13,
        fill=SLATE,
        leading=26,
    )

    s.rect(560, 372, 520, 180, fill=VERAE, stroke="#B7DCC7")
    s.text(576, 400, "Outbound", size=13, fill=OK, weight="700")
    s.lines(
        576,
        426,
        [
            "HTTPS  VERAE_API_BASE_URL  (prod: api.veraetime.net)",
            "NATS   NATS_URL  nats://127.0.0.1:4222",
            "HTTPS  Zapier targetUrl  (webhook worker)",
            "Never bind NATS to a public interface",
        ],
        size=13,
        fill=SLATE,
        leading=26,
    )
    return s.save("08-middleware-internals.svg")


def phases():
    s = Svg(1100, 520, "Implementation phase roadmap")
    s.text(24, 28, "ROADMAP", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "TODO.md phases and gates  ·  do not skip", size=20, fill=NAVY, weight="700")

    done = {
        0,
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        8,
        10,
        11,
    }
    items = [
        (0, "Docs"),
        (1, "Debug"),
        (2, "HTTP"),
        (3, "Store"),
        (4, "Client"),
        (5, "Auth"),
        (6, "Sync API"),
        (7, "NATS"),
        (8, "Workers"),
        (9, "Wait"),
        (10, "Tenancy"),
        (11, "Zapier"),
        (12, "E2E"),
        (13, "Prod"),
        (14, "Push"),
        (15, "Harden"),
    ]

    # chain 0-6
    x0, y0 = 40, 100
    for i, (n, lab) in enumerate(items[:7]):
        x = x0 + i * 150
        fill = TEAL if n in done else PAPER
        tc = PAPER if n in done else NAVY
        st = TEAL if n in done else NAVY
        s.rect(x, y0, 130, 56, fill=fill, stroke=st)
        s.text(x + 65, y0 + 24, f"{n}  {lab}", size=12, fill=tc, anchor="middle", weight="700")
        s.text(x + 65, y0 + 42, "gate passed" if n in done else "open", size=10, fill="#99F6E4" if n in done else MUTED, anchor="middle")
        if i < 6:
            s.harrow(x + 130, x + 150, y0 + 28, color=TEAL)

    # rail from phase 6 down to the three successor rows
    spine_x = x0 + 6 * 150 + 65
    rail_x = 24
    s.raw(
        f'<line x1="{spine_x}" y1="{y0 + 56}" x2="{spine_x}" y2="190" '
        f'stroke="{TEAL}" stroke-width="1.8"/>'
    )
    s.raw(
        f'<line x1="{rail_x}" y1="190" x2="{spine_x}" y2="190" '
        f'stroke="{TEAL}" stroke-width="1.8"/>'
    )
    s.raw(
        f'<line x1="{rail_x}" y1="190" x2="{rail_x}" y2="428" '
        f'stroke="{TEAL}" stroke-width="1.8"/>'
    )

    branches = [
        (40, 210, [(7, "NATS"), (8, "Workers"), (9, "Wait-via-NATS")]),
        (40, 310, [(10, "Tenancy")]),
        (40, 400, [(11, "Zapier app"), (12, "E2E local"), (13, "Production"), (14, "Private push"), (15, "Harden")]),
    ]
    for bx, by, seq in branches:
        s.harrow(rail_x, bx, by + 28, color=TEAL)
        for i, (n, lab) in enumerate(seq):
            x = bx + i * 200
            fill = TEAL if n in done else ("#FEF3C7" if n == 9 else PAPER)
            tc = PAPER if n in done else NAVY
            st = TEAL if n in done else (WARN if n == 9 else NAVY)
            s.rect(x, by, 180, 56, fill=fill, stroke=st)
            s.text(x + 90, by + 24, f"{n}  {lab}", size=12, fill=tc, anchor="middle", weight="700")
            note = "gate passed" if n in done else ("open blocker" if n == 9 else "next")
            s.text(x + 90, by + 42, note, size=10, fill="#99F6E4" if n in done else MUTED, anchor="middle")
            if i < len(seq) - 1:
                s.harrow(x + 180, x + 200, by + 28, color=TEAL if n in done else LINE)

    s.text(24, 500, "Phase 9 is the open blocker before multi-instance wait. Phase 12 needs 8 + 10 + 11.", size=12, fill=MUTED)
    return s.save("09-phase-roadmap.svg")


def workspace():
    s = Svg(1100, 560, "Research workspace and integration path")
    s.text(24, 28, "THIS WORKSPACE", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "How Grok, CLIs, Mongo, and the stack fit together", size=20, fill=NAVY, weight="700")

    s.rect(20, 80, 340, 220, fill=PAPER, stroke=NAVY)
    s.text(36, 108, "Laptop  ·  this repo", size=13, fill=NAVY, weight="700")
    s.lines(
        36,
        132,
        [
            "getting-started.md / .pdf",
            "scratch/veraetime",
            "verae-zapier-api/",
            "docs/diagrams/",
            "/zapier-build skill",
            "scripts/restart-grok.sh",
        ],
        size=13,
        fill=SLATE,
        leading=24,
    )

    s.rect(380, 80, 340, 220, fill=PUBLIC, stroke="#C5D6E8")
    s.text(396, 108, "Local runtime", size=13, fill=TEAL, weight="700")
    s.lines(
        396,
        132,
        [
            "zapier-platform 19.1.0",
            "zapier-sdk 0.77.1",
            "middleware :3100",
            "optional NATS :4222",
            "build + validate (no login)",
            "register / push need ~/.zapierrc",
        ],
        size=13,
        fill=SLATE,
        leading=24,
    )

    s.rect(740, 80, 340, 220, fill=PRIVATE, stroke="#E0D2B4")
    s.text(756, 108, "NS1 Mongo  (tunneled)", size=13, fill=WARN, weight="700")
    s.lines(
        756,
        132,
        [
            "ssh -L 27017:127.0.0.1:27017 ns1",
            "db zapier",
            "apps · templates · help",
            "platform_reference",
            "never 70.88.205.138:27017 public",
            "creds in ~/.mcp-env only",
        ],
        size=13,
        fill=SLATE,
        leading=24,
    )

    s.harrow(360, 380, 190)
    s.harrow(720, 740, 190, label="tunnel")

    s.rect(20, 324, 520, 208, fill=ZAPIER, stroke="#F0D2B8")
    s.text(36, 352, "Publish path", size=13, fill=ACCENT, weight="700")
    s.lines(
        36,
        378,
        [
            "1  validate locally against middleware",
            "2  zapier-platform login  (browser)",
            "3  public HTTPS middleware (Phase 13)",
            "4  register + push private version (Phase 14)",
            "5  one human E2E Zap, then consider listing",
        ],
        size=13,
        fill=SLATE,
        leading=26,
    )

    s.rect(560, 324, 520, 208, fill=PAPER, stroke=NAVY)
    s.text(576, 352, "Consume path  (optional, not Verae publish)", size=13, fill=NAVY, weight="700")
    s.lines(
        576,
        378,
        [
            "zapier-sdk login  →  call existing apps",
            "Hosted MCP  mcp.zapier.com/api/v1/connect",
            "discover → enable → inspect → execute",
            "writes need explicit approval; 2 tasks each",
            "do not mix with zapier-platform",
        ],
        size=13,
        fill=SLATE,
        leading=26,
    )
    return s.save("10-workspace-integration.svg")


def billing():
    s = Svg(1100, 620, "Zapier and Verae billing layers")
    s.text(24, 28, "BILLING", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "Two meters  ·  Zapier tasks  +  Verae timestamps", size=20, fill=NAVY, weight="700")
    s.text(
        24,
        72,
        "Publishing the Verae app is free. The customer’s Zapier plan is not Verae’s invoice.",
        size=12,
        fill=MUTED,
    )

    rows = [
        (88, ZAPIER, ACCENT, "A  Zapier customer plan", "Tasks / month (or Enterprise annual pool)", "Free 100  ·  Pro from 750  ·  Team from 2k  ·  Ent custom"),
        (178, PUBLIC, TEAL, "B  Task multipliers", "1 = typical action (Create Timestamp)", "MCP execute = 2   AI Advanced = 3   Premium = 5"),
        (268, PAPER, NAVY, "C  Overflow", "Pay-per-task on paid plans", "Annual 1.25x  ·  monthly 2.5x  ·  cap 3x then pause"),
        (358, VERAE, OK, "D  Verae middleware plan", "Timestamps / verifications / batch / RPM", "free 50  ·  starter 500  ·  pro 5k  ·  enterprise contract"),
        (448, PRIVATE, WARN, "E  Partner / embed", "Directory publish = $0 to Verae", "White Label: Zapier bills the product co. (usage)"),
        (538, "#F1F5F9", SLATE, "F  Add-ons (not tasks)", "Agents = activities   Chatbots = seat/tier", "Do not mix into the Zapier task estimate"),
    ]
    for y, fill, stroke, title, line1, line2 in rows:
        s.rect(20, y, 1060, 80, fill=fill, stroke=stroke, r=10)
        s.text(40, y + 28, title, size=14, fill=NAVY, weight="700")
        s.text(40, y + 50, line1, size=12, fill=SLATE)
        s.text(40, y + 68, line2, size=12, fill=SLATE)
    return s.save("11-zapier-billing.svg")


def peergos_storage():
    s = Svg(1100, 680, "Timestamped files on Peergos with tiered IPFS and cold retrieve")
    s.text(24, 28, "CLIENT PATTERN", size=11, fill=TEAL, weight="700")
    s.text(24, 50, "Timestamp  ·  metadata  ·  Peergos  ·  pin cache  ·  cold retrieve", size=18, fill=NAVY, weight="700")
    s.text(
        24,
        70,
        "Keep the index hot. Do not keep every CID live on a gateway.",
        size=12,
        fill=MUTED,
    )

    # write path
    s.rect(20, 88, 1060, 200, fill=PUBLIC, stroke="#C5D6E8", r=12)
    s.text(36, 112, "WRITE PATH  (Zapier orchestrates; Verae timestamps the hash)", size=12, fill=TEAL, weight="700")

    boxes = [
        (40, "1  Source", ["Drive / mail /", "Peergos outbox"]),
        (250, "2  Hash", ["SHA-256 or", "envelope JSON"]),
        (460, "3  Verae", ["Create Timestamp", "jobId + hook"]),
        (670, "4  Store", ["Peergos e2e file", "optional hot pin"]),
        (880, "5  Index", ["cid · jobId · class", "always on"]),
    ]
    for x, title, lines in boxes:
        s.rect(x, 128, 190, 132, fill=PAPER, stroke=NAVY)
        s.text(x + 95, 156, title, size=13, fill=NAVY, anchor="middle", weight="700")
        s.lines(x + 95, 182, lines, size=12, fill=SLATE, anchor="middle", leading=20)
    for x in (230, 440, 650, 860):
        s.harrow(x, x + 20, 194)

    # tiers
    s.rect(20, 308, 340, 200, fill=ZAPIER, stroke="#F0D2B8")
    s.text(36, 336, "HOT  ·  cache pin", size=13, fill=ACCENT, weight="700")
    s.lines(
        36,
        362,
        ["Kubo / Pinata / Filebase", "Pinning Services API", "TTL = pinnedUntil", "drop when cold copy exists"],
        size=13,
        fill=SLATE,
        leading=24,
    )

    s.rect(380, 308, 340, 200, fill=VERAE, stroke="#B7DCC7")
    s.text(396, 336, "WARM  ·  Peergos", size=13, fill=OK, weight="700")
    s.lines(
        396,
        362,
        ["e2e encrypted IPFS blocks", "user capabilities / sharing", "host cannot read plaintext", "not a public CDN"],
        size=13,
        fill=SLATE,
        leading=24,
    )

    s.rect(740, 308, 340, 200, fill=PRIVATE, stroke="#E0D2B4")
    s.text(756, 336, "COLD  ·  retrieve on demand", size=13, fill=WARN, weight="700")
    s.lines(
        756,
        362,
        ["S3 Glacier IR / Flexible / Deep", "or Filecoin / B2 / Storj", "Iceberg = catalog, not bytes", "restore API → short re-pin"],
        size=13,
        fill=SLATE,
        leading=24,
    )

    s.rect(20, 528, 1060, 128, fill=PAPER, stroke=NAVY, sw=1.8)
    s.text(36, 556, "READ PATH   GET /ipfs/{cid}  or  gateway miss", size=13, fill=NAVY, weight="700")
    s.lines(
        36,
        582,
        [
            "1  look up index by cid (always-on).   2  pin-hot hit → serve.   3  Peergos capability → fetch encrypted blocks.",
            "4  storageClass glacier-* → StartRestore / vendor retrieve → 202 + Retry-After → rehydrate → optional short pin → serve.",
            "Never walk every pin provider. Never put raw files or Verae JWTs in the Zap.",
        ],
        size=13,
        fill=SLATE,
        leading=22,
    )
    return s.save("12-peergos-ipfs-tiered-storage.svg")


def main():
    high_level()
    security()
    auth()
    flow_async()
    flow_wait()
    nats()
    operations()
    middleware()
    phases()
    workspace()
    billing()
    peergos_storage()
    readme = OUT / "README.md"
    readme.write_text(
        """# Architecture diagrams

SVG sources for [getting-started.md](../../getting-started.md) and `getting-started.pdf`.

| File | What it shows |
|------|----------------|
| [01-high-level-architecture.svg](01-high-level-architecture.svg) | End-to-end stack: Zapier cloud, middleware, NATS, workers, Verae, REST Hooks |
| [02-security-boundaries.svg](02-security-boundaries.svg) | Public HTTPS vs private NATS / store / Verae JWT |
| [03-auth-two-hop.svg](03-auth-two-hop.svg) | User → middleware tokens; middleware → Verae JWT |
| [04-flow-async-timestamp.svg](04-flow-async-timestamp.svg) | Create Timestamp + hook sequence |
| [05-flow-wait.svg](05-flow-wait.svg) | Create and Wait (in-process vs Phase 9 NATS) |
| [06-nats-topology.svg](06-nats-topology.svg) | Streams, subjects, consumers, ack rules |
| [07-operations-map.svg](07-operations-map.svg) | Zapier nouns → `/zapier/v1` → Verae |
| [08-middleware-internals.svg](08-middleware-internals.svg) | Express routes, store, flags |
| [09-phase-roadmap.svg](09-phase-roadmap.svg) | Gates 0–15 |
| [10-workspace-integration.svg](10-workspace-integration.svg) | Repo, CLIs, Mongo tunnel, publish vs consume |
| [11-zapier-billing.svg](11-zapier-billing.svg) | Zapier task plans vs Verae timestamp quotas vs embed |
| [12-peergos-ipfs-tiered-storage.svg](12-peergos-ipfs-tiered-storage.svg) | Timestamp + Peergos + pin cache + Glacier retrieve-on-demand |

Regenerate:

```bash
python3 scripts/generate-diagrams.py
python3 scripts/generate-getting-started-pdf.py
```
""",
        encoding="utf-8",
    )
    print(f"wrote {readme}")


if __name__ == "__main__":
    main()