integration-kit — diagrams

The mermaid sources for this repo. They live here rather than in the README because npm renders no mermaid: on the package page a fence like this one ships as raw DSL. GitHub and the QuxKit docs site both draw them. The README carries an ASCII equivalent of each.

What integration-kit owns, and the seams it hands out

flowchart LR
  subgraph HOST["your app"]
    APP["execute('message.send')"]
    SM["secret manager"]
    DBH["pg.Pool"]
  end
  subgraph IK["integration-kit — Apache-2.0"]
    RT["runtime<br/>templates · retry · mapping"]
    RG["registry<br/>versions · artifacts · lifecycle"]
    CN["connections<br/>tenant config · credential ref"]
    AU["auth resolver<br/>api_key · bearer · basic · oauth2"]
    HL["health"]
    EV["events"]
  end
  PG[("PostgreSQL<br/>integration schema")]
  EXT["external API"]
  APP --> RT
  RT --> RG
  RT --> CN
  RT --> AU
  RT --> HL
  HOST -->|SqlExecutor| PG
  RG --> PG
  CN --> PG
  AU -->|CredentialStore| SM
  RT -->|fetch| EXT
  EXT -->|webhook payload| EV

One execution, end to end

sequenceDiagram
  participant App as your app
  participant RT as runtime
  participant PG as registry (PostgreSQL)
  participant CS as CredentialStore
  participant EX as external API
  App->>RT: execute(connection, 'message.send', input)
  RT->>PG: connection -> published/pinned version
  PG-->>RT: manifest + operation + auth artifacts
  RT->>CS: resolve(credential_ref)
  CS-->>RT: short-lived material
  RT->>EX: POST /messages (templates + auth applied)
  alt 429 / 5xx
    RT->>EX: retry per definition (Retry-After honoured)
  end
  EX-->>RT: 200 { id, created_at }
  RT->>PG: record health (ok, latency)
  RT-->>App: canonical { id, createdAt }

The certification lifecycle

stateDiagram-v2
  [*] --> draft
  draft --> generated : artifacts written
  generated --> testing : test run starts
  testing --> certified : coverage + no failing tests
  testing --> generated : repair
  certified --> published : promote (predecessor deprecated)
  published --> deprecated : superseded
  deprecated --> [*]
  note right of certified : only certified and published execute

Where integration-kit sits in the family

flowchart TB
  ID["identity-kit<br/>(gold)"]
  TN["tenant-kit<br/>(green)"]
  BL["billing-kit<br/>(blue)"]
  ML["mail-kit<br/>(ruby)"]
  CM["comm-kit<br/>(turquoise)"]
  IK["integration-kit<br/>(tanzanite)"]
  OUT["the outside world<br/>CRM · ERP · PMS · custom APIs"]
  ID --> TN --> BL
  ML --> BL
  CM --> BL
  IK --> OUT
  TN -.->|tenant_id on every connection| IK
  BL -.->|meter executions| IK