Architecture

Current Status

GOWDK is compile-first. The current repository discovers .gwdk files, parses page, component, layout, endpoint, client, CSS, asset, and source-import metadata into a typed GOWDK AST, lowers that AST into compiler IR, validates route/render/component/handler contracts, emits manifest/site-map/build-report metadata plus non-served security posture reports, and generates build-time SPA output, generated app source, local binaries, and Go js/wasm deploy artifacts.

Generated build output covers simple static pages, literal dynamic paths {} entries, literal, default go {}, and same-package/imported no-argument build {} data returning T or (T, error), declared layouts, discovered components, page CSS, processor-emitted CSS, partial-update client assets, generated JavaScript island assets, component-level browser WASM island assets, route manifests, asset manifests, source-linked inspect trees, endpoint dispatch graphs, OpenAPI and AsyncAPI inspection artifacts, gowdk-security.json posture reports outside served output, and cache metadata. The build pipeline skips identical generated writes and can incrementally render page-only SPA edits in the dev loop.

Generated apps use runtime/app, generated process lifecycle, and net/http handler contracts. They can serve embedded build output, feature-bound action/API handlers, CSRF-wired action POSTs, first supported action redirect and fragment responses, standalone fragment routes, guards, rate-limit hooks, endpoint panic boundaries, optional generated error documents, concrete and dynamic request-time SSR pages with declared server {} fields, safe local load redirects, and inline go server {} load handlers through the generated request-time route lane. Backend adapter generation lowers request-time endpoint metadata into typed appgen IR before emitting imports, route registrations, request decoders, handler calls, response writing, fallback metadata, split frontend proxy route matching, and backend-only app routing. The app generator uses typed IR and Go AST/printer output before go/format.

runtime/contracts now provides the first local typed registry for queries, commands, backend-owned domain and integration events, presentation events, and jobs. Compiler IR command/query references, .gwdk command/query syntax, local/imported handler and contract-type diagnostics, CLI graph/trace output, and runtime role filtering exist. Generated web adapters can execute routable command/query references through the local registry with the web role, compiler validation rejects web references to non-web-only registrations, and runtime/contracts/fileoutbox provides a dependency-free JSON Lines outbox/EventSource adapter with nack retry metadata and opt-in dead-letter storage. Runtime also includes in-memory broker/EventSource and SSE presentation fanout adapters in the root module. Compiler-validated g:subscribe metadata now binds query-owned DOM regions to presentation-event contracts with exact source spans and build-report metadata; generated apps mount subscription-filtered SSE fanout for bound subscriptions, run inherited guards before opening generated realtime streams, and generated gowdk.js applies explicit replaceHTML realtime patches to the matching query-owned region while rejecting unsupported patch shapes safely. The root SSE adapter declares browser retry timing and drops events for full per-client buffers instead of blocking command execution. Concrete Redis Streams, NATS, and WebSocket adapters live as nested optional Go modules under runtime/contracts so those third-party clients do not enter the root module graph. Durable event envelopes carry stable IDs, workers can use in-memory, file-backed, or Redis seen stores to skip duplicates inside a post-ack deduplication window, and generated apps can expose contract event sink registration, fresh registry construction, and worker replay helpers for executable contract registrations. Event workers can apply explicit nacked-batch backoff options while adapters retain durable retry and dead-letter policy ownership.

runtime/trace provides the first dependency-free GOWDK Trace core. It owns W3C-compatible trace/span IDs, traceparent propagation, context spans, GOWDK surface/lane/source metadata, attributes, events, status, sampling, console/JSONL/ring/multi/exporter sinks, and a bounded in-process JSON/SSE collector. Generated app auto-instrumentation, durable storage, a browser trace viewer, and concrete OTLP transport are later integration work. Debug-gated generated instrumentation now covers backend, SSR/load, contract, browser, and island lanes through addons/observability.

Still partial: broad local client-side reactivity, richer hybrid streaming and data refresh, non-HTTP revalidation, generated worker/cron binary scaffolding, and platform-specific deployment adapters.

System Context

GOWDK users write portable .gwdk pages and components. GOWDK Compiler is the language/compiler layer: it discovers those files, builds compiler metadata, validates render rules, emits assets and generated Go adapters, and packages output for hosted files or app binaries. GOWDK Runtime is the app/runtime layer: it serves generated output, runs request-time handlers, and owns the public runtime/addon packages used by generated adapters.

The target GOWDK Compiler plus GOWDK Runtime output can include spa pages, components, typed actions, API handlers, server fragment handlers, embedded assets, and a Go binary. CSS tooling, including Tailwind, belongs in optional addons rather than the compiler core or runtime core. SSR is enabled only when ssr.Addon() is present and a page opts into request-time rendering.

When this document uses Compiler, it means GOWDK internals under internal/. When it uses Runtime or Addon, it means implementation packages that belong to GOWDK Runtime. Avoid reading those owner labels as separate product names.

Compiler Lanes

Target .gwdk compilation:

.gwdk file
  -> GOWDK parser
  -> GOWDK AST
  -> GOWDK analyzer
  -> generated normal Go code
  -> go/format
  -> go build

Target Go package validation:

.go package directory
  -> go/packages load
  -> standard Go syntax and type information
  -> validate exported handlers/types

The GOWDK AST models .gwdk language constructs. Normal Go files and generated Go source use the standard Go syntax and type information. Analyzer output connects the lanes through package, route, type, component, and handler binding metadata.

Compatibility Records

internal/gwdkir.Program is the single compiler handoff. The pipeline is source -> GOWDK AST (gwdkast) -> IR records (gwdkir) -> program assembly (gwdkanalysis.BuildProgram) -> validation/discovery/binding (compiler) -> generated output (buildgen/appgen). The former internal/manifest compatibility model has been removed entirely:

• internal/parser lowers the typed AST directly into gwdkir page, component, and layout records, including parsed view nodes and typed literal/build-call metadata for supported paths {} and build {} blocks.
• internal/gwdkanalysis.BuildProgram assembles gwdkir.Program from those records (routes, templates, assets, endpoints, packages) and exposes AddStandaloneEndpoints/AttachBackendBindings for the post-assembly enrichment phases.
• internal/compiler validates, discovers standalone Go endpoints, and binds backend handlers against the IR.
• The gowdk manifest JSON report keeps its historical field names but is derived from the IR (internal/lang/manifest_json.go); a golden test pins the output.
• Shared leaf value types (source spans, route params, inline scripts, backend binding records and signature enums, supported backend input field types, error-page path validation) live in the neutral internal/source package.

New generated-output work should consume internal/gwdkir.Program or add fields there first.

No generation path depends on a manifest compatibility record. The remaining manifest references in the tree are not compatibility models: the build-time routeManifest/assetManifest JSON output artifacts (internal/buildgen), the IR-derived public gowdk manifest report (internal/lang/manifest_json.go), the runtime LoadAssetManifest asset lookup, the <… manifest> HTML attribute allow-list (internal/viewparse), and historical-context code comments.

Golden tests pin each handoff stage end to end: AST (internal/parser/testdata/golden), IR (cmd/gowdk/testdata/inspect_ir_golden), routes and endpoints (cmd/gowdk/testdata/routes_golden), generated Go (internal/appgen/testdata/generated_go_golden), generated HTML and route/asset output manifests (internal/buildgen/testdata/full_fixture), and the public manifest report (internal/lang/testdata/manifest_golden).

Components

Data Model

The internal compiler IR includes page identity, source path, route, render mode, layouts, guard metadata, whether spa paths exist, retained paths {} and build {} source text, typed literal/build-call records, parsed view nodes, contract references, realtime subscriptions, and declared blocks. Current public manifest JSON is intentionally smaller: it includes route, effective render mode, layouts, paths presence, and guards. Site-map JSON includes source paths, dynamic params, and block presence for editor tooling.

Generated spa binaries embed this manifest with the rest of the spa output, but request-time generated route handlers do not consume it yet.

Example manifest shape:

{
  "pages": {
    "home": {
      "route": "/",
      "render": "spa",
      "layouts": ["root"]
    },
    "blog.post": {
      "route": "/blog/{slug}",
      "render": "spa",
      "paths": true,
      "layouts": ["root", "blog"]
    },
    "dashboard": {
      "route": "/dashboard",
      "render": "ssr",
      "layouts": ["root", "dashboard"],
      "guard": ["auth.required"]
    }
  }
}

API And Integration Contracts

Application config:

var Config = gowdk.Config{
	AppName: "Clinic",
	Source: gowdk.SourceConfig{
		Include: []string{
			"src/**/*.gwdk",
		},
	},
	Modules: []gowdk.ModuleConfig{
		{Name: "frontend", Type: "frontend"},
		{
			Name: "admin",
			Type: "admin-ui",
			Source: gowdk.SourceConfig{
				Include: []string{"frontends/admin/**/*.gwdk"},
			},
		},
		{
			Name: "backendmicroservice",
			Type: "backendmicroservice",
			Source: gowdk.SourceConfig{
				Include: []string{"services/backend/**/*.gwdk"},
			},
		},
	},
	Render: gowdk.RenderConfig{
		Default: gowdk.SPA,
	},
	Build: gowdk.BuildConfig{
		Output: "dist/clinic",
		Assets: gowdk.Embed,
	},
	Addons: []gowdk.Addon{
		SPA.Addon(),
		actions.Addon(),
		partial.Addon(),
		embed.Addon(),
		ssr.Addon(),
	},
}

Block semantics:

• paths {} runs at build time and declares dynamic spa routes.
• build {} runs at build time and feeds spa rendering.
• server {} runs at request time and requires SSR or hybrid rendering.
• act Name POST "/path" declares POST/action endpoints.
• api Name METHOD "/path" declares API endpoints.
• view {} renders markup.

Target generated route behavior:

mux.HandleFunc("GET /", embedded.SPA("pages/home.html"))
mux.HandleFunc("POST /newsletter", actions.NewsletterSubscribe)
mux.HandleFunc("GET /dashboard", ssr.RenderDashboard)
mux.HandleFunc("GET /api/patients", api.PatientsIndex)

The current code can plan route metadata for CLI reports and can emit SPA HTML files, CSS assets from compile-time processors and discovered page CSS inputs, stylesheet links, page-aware processor stylesheet selections, gowdk-routes.json, gowdk-assets.json, gowdk-build-report.json, the partial-update client runtime, and generated island runtime assets when needed for simple build-time pages with explicit or discovered component and layout files. It expands the first literal paths {} subset for dynamic SPA routes, binds those route params plus literal build {} data or imported Go build data into the current SPA view {} interpolation context, resolves typed component props/state contracts from Go module imports, runs state init functions at build time, and composes SPA page layouts through each layout's single <slot />; literal build {} string values can also interpolate current route params. It parses the supported action body subset and can generate SPA POST redirect handlers plus form input decoders, required-field validation wrappers, typed same-package action decoder glue, user action/API calls, CSRF token wiring by default for generated action POSTs, command POSTs, and state-changing APIs, partial fragment responses, and concrete or dynamic standalone fragment routes through runtime/partial; dynamic fragment params are attached to hook contexts through runtime/app.Params(ctx) and runtime/app.TypedParams(ctx). gowdk build --app can also generate concrete and dynamic SSR routes for pages with request-time full-page behavior, with dynamic route matching, generated typed route-param bindings backed by runtime/route, and server {} execution for declared fields through runtime/ssr; generated SSR load functions can return safe local redirects, generated SSR load failures can render optional 500.html, and generated apps can render optional 404.html for not-found responses. Generated guarded SSR, action, API, and fragment routes use auth.Addon defaults for auth.required and native role:/permission: session guards when configured; otherwise they require GOWDKGuardRegistry for custom guard IDs and GOWDKAuthProvider for native RBAC guard IDs, fail Go compilation when required backing hooks are missing, and run declared guards through runtime/guard before user logic. Ordinary guard errors fail closed while explicit guard helper errors can write no-store redirects or custom responses. Generated SSR, action, and API lanes also recover panics before response headers are written as no-store HTTP 500 responses without exposing panic values. gowdk build --app can generate an embedded Go app from that output, --bin can compile it, and --docker can emit a minimal Docker context beside the compiled binary. gowdk serve can serve the generated SPA directory locally. It does not implement arbitrary client expressions yet. Only pages with server {} or go server {} should use request-time full-page rendering.

Guard metadata declarations are parsed and exposed in manifest/site-map output. runtime/guard defines guard context, registry, ordered execution, no-store redirect/custom-response helpers, and native RBAC resolution for generated action, API, fragment, and SSR routes. runtime/auth defines the thin native RBAC principal/provider contract used for generated route access gates. runtime/ssr owns guard type aliases for new code; addons/ssr re-exports them for existing SSR-facing code, but generated action/API/fragment output does not import SSR only to run guards. Generated handlers enforce declared guard IDs before request-time user logic. Generated app packages with guarded routes use auth addon defaults when configured, or require app startup code to define GOWDKGuardRegistry or GOWDKAuthProvider without feature packages importing generated output. Missing required guard backing hooks fail Go compilation. Backend resource authorization still belongs in normal Go handlers and services; generated guards are redundancy, not the source of truth.

Language tool commands:

gowdk tokens <file.gwdk>
gowdk fmt [--write] <file.gwdk>
gowdk check [--ssr] <file.gwdk>
gowdk manifest [--ssr] <file.gwdk>
gowdk sitemap [--ssr] <files>
gowdk build [--config <file>] [--debug] [--ssr] [--target <name>] [--module <name>] [--out <dir>] [--app <dir>] [--bin <file>] [--docker] [--docker-base <distroless|scratch>] [--wasm <file>] [files...]
gowdk dev [--addr <addr>] [--interval <duration>] [build flags...]
gowdk serve --dir <dir> [--addr <addr>]
gowdk lsp [--ssr]

The user-facing documentation set for this pipeline is:

• docs/getting-started.md for clone, build, scaffold, build, and serve.
• docs/reference/cli.md for working commands and flags.
• docs/reference/config.md for the spaally loaded config subset.
• docs/reference/routing.md for route validation, route plans, and generated route behavior.
• docs/reference/deployment.md for spa, generated app, binary, and WASM deploy outputs.
• docs/compiler/pipeline.md and docs/compiler/browser-compiler.md for compiler and browser-facing output stages.
• docs/language/ for supported and unsupported .gwdk syntax.
• examples/README.md for examples that match the actual compiler slice.

Project-level compiler commands load gowdk.config.go from the current directory, or an explicit --config <file>, before compiling, validating, or inspecting .gwdk code. Explicit file paths narrow the input set but do not bypass the config requirement. When gowdk build receives no explicit files, it loads literal root source, module source, and build target settings from the config. A module with a name but no explicit include defaults to <module-name>/**/*.gwdk. Configured Build.Targets declare named module sets, output dirs, generated app dirs, binary paths, and WASM paths; with targets configured, gowdk build runs every target and --target <name> limits the run to selected targets. --module <name> remains available for ad hoc builds and may be repeated or comma-separated. The selected modules define the source set compiled into --out, copied into --app, and embedded into --bin or --wasm, so projects can build one-module binaries, multi-module binaries, WASM artifacts, or different artifacts from different module sets. If the loaded config has no root or module includes, discovery uses **/*.gwdk under the current working directory. Discovery excludes .git, vendor, node_modules, testdata, configured source excludes, and the selected output directory. Module type is user-defined metadata today; future generated-output work can use it to separate frontend, backend, and service artifacts. The VS Code extension uses gowdk sitemap to render a visual route map. Because routes are declared inside .gwdk files, the visualizer can move a page file without changing the page route.

LSP-capable editors can use gowdk lsp over stdio for live buffer diagnostics, document formatting, completions, and hover. The first LSP version uses full-document synchronization and validates one open buffer at a time with the same parser and compiler rules as gowdk check.

Key Quality Attributes

• Scalability: spa output should serve without request-time page rendering.
• Reliability: invalid render modes and missing addon requirements must fail at compile time.
• Security: actions must own form decoding, validation, CSRF, and redirect behavior.
• Observability: manifests and site maps should explain route behavior and render mode.
• Maintainability: runtime render core stays separate from addons/ssr.

Diagrams

flowchart LR
  Source[.gwdk files] --> Discover[internal/discover]
  Discover --> Parser[internal/parser]
  Parser --> IR[internal/gwdkir records]
  IR --> Assembly[internal/gwdkanalysis]
  Assembly --> Compiler[internal/compiler]
  Compiler --> Buildgen[internal/buildgen]
  Compiler --> Appgen[internal/appgen]
  Buildgen --> SPA[SPA pages/assets]
  Appgen --> Binary[one Go binary]
  Embed[addons/embed] --> Binary

  Render[runtime/render] --> StaticAddon[addons/static]
  Render --> ActionsAddon[addons/actions]
  Render --> PartialAddon[addons/partial]
  Render --> SSRAddon[addons/ssr]
  Guard[runtime/guard] --> ActionsAddon
  Guard --> APIAddon[addons/api]
  Guard --> PartialAddon
  Guard --> SSRAddon