Compiler & runtime architecture

This page is for developers who want to understand IWC's internals — to debug a surprising behaviour, contribute a feature, or build tooling on top. For the conceptual overview, read How IWC works first.

IWC is written in Go. The CLI, compiler and runtime are one statically linked binary with two dependencies: a pure-Go SQLite driver and pgx for PostgreSQL. The standard library covers HTTP, JSON, crypto and embedding.

Source layout

Package	Responsibility
`cmd/iwc`	The CLI: every command, flag parsing, the dev server's watcher and terminal output, plugins
`internal/jsonpos`	A strict JSON parser that records the line and column of every value. Duplicate keys, trailing commas and comments are errors
`internal/schema`	The shape of every file type, validation against it, and JSON Schema export (`iwc schema`)
`internal/project`	Loading a project, linking files together, cross-file and semantic checks, and the resolved model
`internal/expr`	The expression language: parser, evaluator, the function whitelist, formats and money
`internal/render`	Server-side HTML rendering of screens, scoped CSS, icons, SEO tags, Markdown, the browser runtime modules
`internal/server`	The HTTP engine: routing, pages, APIs, auth and sessions, access rules, actions, jobs, live updates, uploads, OAuth, MFA, PWA, OpenAPI
`internal/data`	The database layer for SQLite and PostgreSQL: queries, aggregates, migrations, backups, field encryption
`internal/integrations`	The `@iwc/*` package providers (payments, mail, push, storage, AI…), built into the binary
`internal/egress`	Outbound HTTP with SSRF protection: the dialled address is checked after DNS resolution; redirects are not followed
`internal/native`	Lowering screens to Jetpack Compose and SwiftUI projects, toolchain checks, device runs, smoke tests
`internal/sdui`	Server-driven native apps: turns a rendered screen into a view tree native renderers draw
`internal/audit`	`iwc security`: reviews a compiled project for risky but legal configurations
`internal/perf`	Route size reports and budgets (`iwc build --report`)
`internal/build`, `internal/deploy`	Production bundles and the release agent behind `iwc host` / `push` / `rollback`
`internal/testrun`	Runs `.test.iwc` files against an isolated in-memory instance
`internal/secrets`	The development vault, secret scanning, and log redaction
`internal/scaffold`	The `iwc create` starters

The compiler pipeline

Load (project.Loader): walk the directory, classify files by extension, skip dot-folders and output folders, read each file once.
Parse (jsonpos): strict JSON with positions.
Validate (schema.Validate): each file against its type's schema, producing positioned diagnostics with suggestions for near-miss keys and enum values.
Link (project/link*.go): resolve every file reference; check element/property applicability, data-source columns against schemas, expression scopes, access-rule references (roles, permissions, scopes), offline queueability, widget policies, native renderability; reject literal secrets.
Model (project.Project): pages with their layouts, components and styles; APIs with their implementations; schemas with tables; actions with steps.

Every stage reports diagnostics instead of stopping at the first error, so one iwc check shows everything that is wrong.

The runtime

server.Engine holds the compiled project, the database handle, the job queue, the live-update hub and the rate limiters.

Pages run their data sources through the access layer, render HTML through render, and add a per-request CSP nonce.
APIs validate the request contract, check CSRF/auth/roles/permissions/scopes/rate limits/idempotency, run exactly one implementation (operation, action or workflow), and filter the response to declared fields.
Access (server/access.go) turns a schema's access rules into row conditions for every generic read and write; actions are trusted and skip row rules but keep tenancy.
Actions execute steps with an expression scope (input, user, request, integrations…) inside an optional transaction; callAction nests transactions; emitted events and enqueued jobs commit with it.
Jobs are rows in _iwc_jobs, claimed by workers, retried with exponential backoff, and survive restarts.
Live updates: writes notify a hub; browsers subscribed over Server-Sent Events (/_iwc/events) re-fetch affected fragments (/_iwc/fragment).

Package management

Capabilities that need third-party services ship as packages inside the binary (iwc packages): one IWC-native interface per capability and several interchangeable providers behind it. iwc add writes a .integration.iwc, stores credentials in the encrypted vault and verifies the connection. Nothing is downloaded at install time and no third-party code runs in your app. Browser widgets (@iwc/map, @iwc/richtext…) are copied into widgets/ and become yours.

Extensibility

Mechanism	Use it for
`x-` keys in any file	Data for other tools (visual editors, generators); IWC keeps and ignores it
CLI plugins	`iwc <name>` runs `iwc-<name>` from `~/.iwc/plugins` or `PATH`, with `IWC_BIN`, `IWC_VERSION`, `IWC_CWD`
`.service.iwc`	Any HTTP API, without a package
Widgets	Your own browser JavaScript behind a declared CSP
Native extensions	Your own Kotlin/Swift called from a button with `"action": "native"`
JSON Schemas	`iwc schema` for editors and generators

Performance

Pages are rendered on the server; each route loads only the runtime modules its elements use; CSS is bundled and content-hashed; data sources select only listed columns. Budgets per route are checked on every build. See Performance & budgets.

Testing and debugging

.test.iwc cases run against an in-memory instance (SQLite) or a throwaway PostgreSQL schema, with sign-in (as), saved values (save/{{name}}) and due jobs run after each request.
iwc logs -f shows each request and, for failures, the reason.
The IWC repository's own go test ./... validates every documentation snippet against the schemas and runs every example project and archetype.

See Debugging & testing and Limitations.

Source: apps/marketing/content/docs/architecture.md