Skmtc Architecture

SKMTC architecture

This skill is the system mental model for agents building infrastructure around SKMTC — a hosted generation service, a schema or generator registry, provenance and tracing tooling, a web app that wraps the engine. It explains what SKMTC is, how it works, and why it behaves the way it does — deeply enough to reason about and extend, without the generator-authoring or CLI-operating detail the sibling skills carry.

SKMTC is counter-intuitive on purpose. Most of what generic codegen and generic backend-infra training data would suggest is actively wrong here. The fastest way to make a bad architectural proposal is to extrapolate from another tool. Read §1 and §11 before proposing anything.

1. The five facts that override default LLM intuitions

These override what training-data priors suggest about codegen tools. They apply across every SKMTC interaction; an infra builder needs facts 1, 2 and 5 most.

1. No plugin registry, no dependency graph, no topological sort. Cross-generator coordination is a Map cache keyed by (identifier.name, exportPath). Generator execution order does not affect output.

2. Render does not run Prettier or Biome. No formatter runs inside @skmtc/core. Generated output is unformatted by design; consumers format separately.

3. Generator source code is the customization surface. Stock generators have deliberately hardcoded export paths and peer imports. To customize beyond enrichments: clone the generator and edit it. There are no config flags for paths or output shape.

4. OasSchema is a union type, not a class hierarchy. Sibling classes (OasObject, OasArray, OasString, …) each independently implement .isRef() returning false. OasRef is a sibling with .isRef() returning true. There is no BaseSchema.

5. Every generation run is from cold. One Deno Worker is spawned per generate, runs Parse → Generate → Render once, posts the result back, and is terminated. No warm pool, no cross-run cache, no incremental rebuild. toArtifacts is a pure function of (document, settings, generators). Determinism is chosen over speed deliberately — caching belongs outside the engine, keyed on input hashes.

2. What SKMTC is

SKMTC is a code generator. It takes one OpenAPI v3 document or one GraphQL SDL schema and produces source files — types, runtime validators, query hooks, forms, mocks, server routes — all derived from that one schema, in one run, all consistent with each other. The output is committed to the consumer's repository like any other source code; there is zero SKMTC runtime in the consumer's bundle. The engine is language-blind (core 0.8.0+): a generator declares its target language by importing its projection-base factories and snippet base from a @skmtc/lang-* package — the import graph alone carries the language; entries have no lang field. TypeScript (@skmtc/lang-typescript) and Kotlin (@skmtc/lang-kotlin, proven by gen-kotlin DTOs + gen-kotlin-spring controllers) are the production languages; other lang-* packages (C#, …) are the roadmap.

The crucial reframing for an infrastructure builder: SKMTC is an engine with several thin hosts, not a CLI. The CLI is one host. The mental decomposition:

Every host does the same thing: get a schema, call toArtifacts, do something with { artifacts, manifest }. A SaaS is just another host of the same engine.

3. What you get — the benefits

• Multi-artifact coherence. One schema yields N artifact types (types + validators + hooks + forms + mocks + routes) that reference each other correctly. Add a field, regenerate, every artifact updates consistently.
• Output is committed source code. Reviewable in git diff, grep-able, refactorable. No runtime library, no peer-dependency package at deploy time. Schema/output drift is visible in version control.
• Determinism. Same inputs → byte-identical output. No hidden state, no order dependence, no warm-cache effects.
• Idempotency by construction. Generators coordinate by memoization, not by a dependency graph — so they can be written, tested, and reasoned about in isolation, and order never matters.
• Clone-to-customize. Generators are owned source code, not opaque configured dependencies (the shadcn/ui model).
• Lenient input, strict diagnostics. One malformed schema does not kill the run; it is logged and its dependents pruned. The manifest.json is an exhaustive record even when output is partial.
• OAS and GraphQL through one engine. The GraphQL pipeline reuses the same DSL, the same renderer, the same manifest.

4. When to use SKMTC — and when not to

SKMTC's closest peer is kubb — multi-target, TypeScript-native. The distinguishing bet is the customization model: clones (source you own) over plugins (configured packages), plus coordination by name (memoization) over explicit composition. Full landscape: explanation/comparison-to-other-tools.md.

5. How it works — the pipeline

A generation run is a one-way pipeline of three phases, each producing an immutable artifact the next consumes:

        ┌─────────────── HOST PROCESS ───────────────┐
        │  bootstrap · fetch schema · OAS pre-parse   │
        └──────────────────────┬──────────────────────┘
                               │  postMessage(GENERATE)
        ┌──────────────────────▼──────────────────────┐
        │        DENO WORKER  (sandboxed)             │
        │   PARSE  ─▶  GENERATE  ─▶  RENDER            │
        │   model     files map      { path: text }   │
        │   +issues   (in memory)    artifacts        │
        └──────────────────────┬──────────────────────┘
                               │  postMessage(RESULT)
        ┌──────────────────────▼──────────────────────┐
        │  HOST: write files to disk · write manifest │
        └─────────────────────────────────────────────┘

• Parse — schema → typed object model (OasDocument / GqlDocument). Lenient: a per-item parser that throws becomes a ParseIssue; removeErroredItems then prunes one hop of $ref consumers of any failed component. Generate can trust every surviving item.
• Generate — walk the configured generators over the parsed document, producing an in-memory Map<path, File>. Generators produce output via side effects (register / insert*), never by return value. Memoized Drivers dedupe and coordinate (§6).
• Render — serialize each File to a string by joining re-exports, imports, and definitions. No formatter runs. Output is Record<path, content>.

Each phase boundary is an immutable hand-off — the next phase reads, never mutates. Detail: concepts/the-three-phases.md.

The host / Worker boundary

The engine physically runs in a Deno Worker spawned by the host, one per run (fact 5). The boundary is postMessage, which uses the structured-clone algorithm — and that shapes a real asymmetry:

• OAS is parsed host-side. A plain OpenAPIV3.Document is JSON — it survives structured clone. The host normalizes Swagger 2 / OAS 3.1 to 3.0 via @skmtc/convert, then posts the plain document.
• GraphQL is parsed Worker-side. A parsed GqlDocument has class instances with cyclic back-references — structured clone strips methods and prototypes. So the host posts the raw SDL string and the Worker parses it.

The Worker boundary is also the security boundary. The Worker is spawned with Deno permissions read: true, write: true, env: true, net: false, run: false. Generator code (third-party JSR packages or team-edited clones) cannot make network calls or spawn subprocesses. It is a soft sandbox — it limits the blast radius of a buggy or compromised generator, not a determined attacker. Schema fetching happens host-side, before the Worker exists. Detail: concepts/the-worker-runtime.md, explanation/security-model.md.

The engine entry point

Every host calls one function:

toArtifacts({
  traceId, spanId, startAt,          // run correlation
  document,                          // SkmtcDocumentInput (oas | gql)
  settings,                          // ClientSettings (basePath, enrichments, skip, include)
  toGeneratorConfigMap,              // () => the registered generators
  stackTrail,                        // position/trace stack
  silent,
  attribution                        // optional — turns on gen-maps (§8)
}): { artifacts: Record<string,string>; manifest: ManifestContent;
      sidecars?; generationMap? }

It is pure with respect to its inputs and does no I/O of its own beyond reading. core/run/toArtifacts.ts, worker/mod.ts, and server/src/createServer.ts are three independent callers of it — study them as the templates for a fourth.

6. How it works — cross-generator coordination

This is the single most counter-intuitive piece. There is no dependency graph and no topological sort. Coordination is memoization:

• A generator that needs a peer's output calls this.insertOperation(PeerProjection, op) (or insertModel / insertNormalizedModel).
• A Driver (OasOperationDriver, GqlOperationDriver, ModelDriver) computes a cache key (identifier.name, exportPath) — both pure functions of (operation, enrichments) via the peer's static methods.
• Cache hit → the existing Definition is reused. Miss → the peer's Projection is constructed (which may recurse), wrapped in a Definition, registered, and its import stitched into the calling file.

Because the key is a pure function of inputs, whichever generator asks first triggers construction and everyone after gets a cache hit — so the output Map<path, File> is identical regardless of generator order. A generatorKey integrity check throws "Registered definition mismatch" if two different generator-and-input pairs collide on one cache key.

Why this matters for infra: order-independence means there is nothing to schedule or sequence. Determinism means the correct caching layer is outside the engine — cache the whole { artifacts, manifest } result keyed on a hash of (schema, settings, bundle). Never try to cache inside a run. Detail: concepts/cross-generator-coordination.md.

7. The DSL in one screen

You do not need to author generators to build infrastructure, but you should recognize the vocabulary (defer authoring to skmtc-generator):

• A generator is a JSR package exporting an entry built with toOasOperationEntry / toGqlOperationEntry / toModelEntry. Entries are pure pipeline config — no lang field; the generator declares its target language by importing its projection bases from a @skmtc/lang-* package, and the engine's Drivers read it off the projection class's inherited static.
• The entry's transform hook runs once per matched operation/model and produces output by calling register / insert* — its return value is discarded.
• A Projection is a named, file-scope artifact (export const X = …), wrapped in a Definition, cached by (name, exportPath), reachable by other generators. A Snippet is an anonymous fragment embedded into a Projection's body via template-literal interpolation.
• Templates are TypeScript template literals inside classes — not .hbs/.mustache files. Composition is by ${...} interpolation of anything Stringable. (Generators are authored in TypeScript/Deno regardless of the target language they emit.)

Vocabulary discipline: in SKMTC prose use register, insert, render. Avoid emit, dispatch, stitch — they map to no exported surface. See reference/glossary.md.

8. The manifest — the run contract and tracing

Every run writes a manifest.json (to .skmtc/<project>/.settings/manifest.json for the CLI host; returned in-band for the HTTP host). It is the canonical record of a run — written always, even on failure. The terminal output is a summary; the manifest is the full story.

type ManifestContent = {
  deploymentId: string      // the run; from DENO_DEPLOYMENT_ID or a timestamp
  traceId: string           // OpenTelemetry-shaped correlation key
  spanId: string            // sub-span within the run
  region?: string           // set only for hosted (Deno Deploy) runs
  files:    Record<path, { lines, characters, destinationPath }>
  results:  ResultsItem     // nested tree of per-(generator × item) outcomes
  previews, mappings        // optional UI metadata (per-Definition source descriptors)
  parseIssues: ParseIssue[] // every Parse-phase diagnostic
  startAt, endAt: number    // unix ms; endAt - startAt = worker wall time
}

What an infra builder must internalize:

• Tracing is built in. traceId / spanId are OpenTelemetry-shaped. The StackTrail carries them as its root frames, and the results tree is keyed by stack-trail strings — so an outcome is addressable as traceId → spanId → generate → generatorId → item. deploymentId and region come from Deno Deploy env vars on the hosted path. Wire these straight into an observability backend.
• Exit / status derives from parseIssues, not from throws. The CLI returns exit 1 iff any parseIssue.level === 'error'. The engine fails open — a bad schema does not throw, it logs. Your HTTP host must compute status from manifest.parseIssues, not from a try/catch around toArtifacts.
• results outcomes: success means "the transform ran without throwing" — not "produced output". notSupported is normal (a generator that doesn't apply to an item). skipped is filter exclusion. Diagnose "no output" via the files map, not results.
• No history. The on-disk manifest is overwritten every run. If you want run history, persist each manifest yourself — it is already the right per-run telemetry payload.

Detail: concepts/the-manifest.md, reference/manifest-format.md.

9. Provenance — the attribution / gen-maps subsystem

core/anchors/ is the provenance layer. Capture is always on; emission is opt-in: pass attribution: { postPass: {...} } to toArtifacts (the engine-level AttributionState has no enabled field — the client.json#settings.anchors.enabled switch is the user-facing toggle). When emission is on, the run produces two extra artifact types alongside the code:

• Sidecar (<file>.skm.json) — one per generated file. A pooled, position-indexed map: byte ranges in the rendered file → attribution tuples { genId, srcPtr, variant, defName }, plus generator version and source registry. It is a source map for provenance — it answers "which generator, which schema location, which variant produced this span of code?". srcPtr is a schema pointer like oas:#/components/schemas/User.
• Generation map (_map.ndjson) — a project-level, per-Definition reverse-query index: "which files came from refName User?", "which files did gen-zod produce?". Wholly rewritten each run.

Both live under .skmtc/<project>/.maps/ (gitignored by default). Mechanism: SnippetBase instrumentation caches each producer's rendered text; a post-pass walks the producer tree and AST-resolves byte spans to landmarks. The AST parser (oxc-parser) does not bundle into a Worker, so inside the Worker landmark names come from Definition identifiers and a host-side post-pass can fill AST detail later.

A lighter, always-on channel exists too: the manifest's previews and mappings pair a per-Definition module with a source descriptor ({ generatorId, operationPath, operationMethod } etc.) — enough for a UI to say "this form was generated from POST /contacts".

If you are building provenance or "trace generated code back to its schema" tooling, build on this subsystem (Sidecar, GenerationMapEntry, AttributionState — exported from @skmtc/core/Anchors). Do not reinvent it.

Full treatment — the four-stage mechanism, the Sidecar v2 format, the worker-side parser omission, the doctor checks: attribution-and-gen-maps.md.

10. The package graph and dependencies

The @skmtc/* packages

@skmtc/openapi-down-convert   (OAS 3.1 → 3.0, vendored fork)
        ▲
@skmtc/convert                (Swagger 2 / 3.1 → 3.0; YAML/JSON parse)
        ▲
@skmtc/core ◀───────────────── the engine; depended on by everything
        ▲   ▲   ▲   ▲
        │   │   │   └── @skmtc/gen-*   (generators; + peer generators)
        │   │   └────── @skmtc/server  (Hono HTTP host)
        │   └────────── @skmtc/worker  (Deno Worker host)
        └────────────── @skmtc/cli ──▶ @skmtc/mcp (MCP host wraps the CLI)

cli also depends on convert and worker. Exact versions live in each package's deno.json — treat that as canonical, not this skill.

The substrate

SKMTC's design principle "build on the substrate, don't rebuild it" means Deno is the platform:

• deno bundle is the bundler — it compiles a project's worker.ts into bundle.js.
• new Worker(...) with deno.permissions is the sandbox.
• JSR is the package registry. Generators and packages are ordinary JSR packages — there is no bespoke registry layer (that was explicitly rejected). Two registries are in play: jsr.io (public) and jsr.skmtc.dev (the SKMTC private registry).
• The hosted Sandbox API runs on Deno Deploy (hence DENO_DEPLOYMENT_ID / DENO_REGION flowing into the manifest).

The project is Deno-locked, and that is an accepted trade. The generated output, however, runs anywhere TypeScript runs.

Key third-party dependencies

Version-pin discipline: inter-package @skmtc/* dependencies are pinned to exact JSR versions — no caret ranges — so a cloned generator and the engine it compiles against can't silently skew. skmtc doctor checks that a project's @skmtc/core pin matches the CLI's. Pins can lag between packages; always read deno.json.

11. Building infrastructure around SKMTC

The user's context: a GitHub-like SaaS for hosting APIs and generators, running them, and supporting tracing and provenance. Here is how the engine's concepts map onto that platform — and where the engine stops and your platform code begins.

The integration map

@skmtc/server is the seed of the SaaS

server/src/createServer.ts is ~150 lines: a Hono app with POST /artifacts (validate a discriminated body → convert → toArtifacts → { artifacts, manifest }), GET /generators, and POST /to-v3-json. A production run service is this pattern with auth, tenancy, persistence, and bundle management added around it. The MCP host already calls a deployed instance of this server.

Where the engine stops — build these at the platform layer

The engine deliberately does schema in → artifacts out and nothing else. It has no notion of:

• Users, identity, auth, multi-tenancy. A SKMTC "project" is a generator configuration, not a tenant. Tenancy is entirely yours to build.
• Persistence or run history. toArtifacts returns a value; the on-disk manifest.json is overwritten every run.
• Result caching. Determinism makes this safe and easy — cache { artifacts, manifest } by a hash of (schema, settings, bundle) — but it is your layer, never the engine's.
• A warm execution pool, rate limiting, quotas, streaming. Fact 5: one cold Worker per run. Pool at the container/process level if you need throughput; never share a context across runs.
• A plugin / hook API. There isn't one and it is a rejected design. Extension happens by cloning generators or by writing a new host — not by hooking the engine.

12. Counter-intuitive facts for infrastructure builders

Beyond the five facts in §1. Left column = a reflex from generic backend / platform training data; right column = SKMTC reality.

13. Boundaries with other skills

• skmtc-generator — authoring and editing generators (Projections, Snippets, the DSL, customization seams). Load when writing generator code.
• skmtc-cli — running the CLI, configuring client.json, enrichments, skip/include. Load when operating SKMTC.
• skmtc-debug — diagnosing broken runs (no output, wrong output, errors). Verify-first stance. Load when something is broken.
• skmtc-retro — end-of-session reflection / friction capture.
• This skill (skmtc-architecture) — the system mental model for reasoning about and building infrastructure around the engine.

If the question is how the system works or how to build a service around it, this skill. If it is how to write a generator, how to run a command, or why a run is broken, hand off.

14. Cross-references

Concepts — the-three-phases.md · the-worker-runtime.md · the-manifest.md · stack-trail.md (reference) · cross-generator-coordination.md · generators-as-packages.md · attribution-and-gen-maps.md

Explanation — design-philosophy.md · security-model.md · comparison-to-other-tools.md · status-and-roadmap.md

Reference — glossary.md · manifest-format.md · llms.md (consolidated operational reference)

Source landmarks — core/run/toArtifacts.ts (engine entry) · worker/mod.ts (Worker host) · server/src/createServer.ts (HTTP host) · core/context/ (the three context classes) · core/anchors/ (attribution / gen-maps).