# GizStack Platform Architecture

Gizlang provides a vertically integrated native software stack where language semantics, data models, storage engines, network protocols, user interfaces, and AI execution share a single source of truth. Rather than stitching together external ORMs, serialization schemas, message brokers, and web frameworks, one typed declaration drives the entire lifecycle from disk layout to live browser updates and agent tool invocations.

## Architectural Principles

1. **Single Source of Truth (`Shape`, `Policy`, `Operation`)**: A record definition in `gizmodel` simultaneously defines SQL table schemas, binary wire codecs, form validators, access control policies, and strongly typed agent tool signatures.
2. **One Owner, One Copy**: Every cross-cutting concept has exactly one canonical implementation module enforced by `bin/gizlang structure` against `structure/concepts`. Higher layers extend or compose the owner module rather than introducing parallel abstractions.
3. **Zero-Copy Native Execution**: Programs compile via LLVM to native machine code (`x86-64` with runtime dispatch for `v2`/`v3`/`v4` SIMD levels, `aarch64`, `riscv64`, and freestanding bare-metal targets) linked against a deterministic C/Gizlang runtime.
4. **End-to-End Reactivity**: Committed transactions in [GizDB](database.md) and revision updates in [GizFS](storage.md) publish directly to the change feed, streaming incremental DOM patches over [GizWeb](web.md) live views without polling.

## End-to-End Stack Dataflow

| Layer | Canonical Package | Responsibility | Primary Internal Reference |
| --- | --- | --- | --- |
| Language & Compiler | `compiler`, `compiler-driver` | Lexing, parsing, ownership/effect checking, LLVM IR emission, and sub-100ms live incremental rebuilds | [Compiler internals](compiler.md) |
| Runtime & OS | `runtime`, `sdk` | Generational precise heap, task scheduler, `io_uring`/libuv I/O, freestanding C library, and per-process isolation and confinement | [Runtime](runtime.md), [Memory](memory.md), [System](system.md) |
| Hardware & Compute | `hw`, `ai` | CPU/cache topology, CUDA/Vulkan/Metal GPU kernels, tensor autograd, LLM/diffusion inference, and classical ML | [Compute internals](compute.md), [Hardware guide](../guides/hardware.md) |
| Storage Engine | `fs` | Raft-replicated storage ranges, Reed-Solomon erasure coding, content-addressed blobs, S3 gateway, and FUSE/ublk mounts | [Storage internals](storage.md) |
| Data & Query Engine | `model`, `db`, `db-ml` | Typed relational/document/KV/vector engine, PostgreSQL wire protocol, HNSW vector search, and in-database ML (`pgml`) | [Database internals](database.md), [SQL ML](sql-ml.md) |
| Web, Browser & UI | `web`, `browser`, `apps` | `.ghtml` server-rendered & live views, design system tokens, zero-syscall HTML/CSS layout engine, and Wayland desktop shell | [Web internals](web.md), [GHTML reference](../reference/ghtml.md) |
| Polyglot VM & Workspace | `vm`, `vm-lua`, `desk` | JS/TS/Python/Wasm/Lua virtual machines, CPython/N-API coroutine bridges, and the GizDesk agent workspace | [VM internals](vm.md), [GizDesk guide](../guides/desk.md) |

## Shared Platform Concepts

The table below is generated and verified by `bin/gizlang structure --doc` from `structure/concepts`. Defining any reserved type or calling any reserved constructor outside its owner file fails the structural check.

<!-- structure:concepts -->

| Concept | Owner file | What it is | Names reserved to it |
| --- | --- | --- | --- |
| `Policy` | `model/policy.giz` | Grants and the row and field rules that the data layer enforces (the one list of who may do what) | `Policy` |
| `Operation` | `model/model.giz` | Every change as a typed input and result with risk, idempotency, approval, audit and meter | `Operation` |
| `Shape` | `model/model.giz` | The one type source that a table, a form and a view all follow | `Shape` |
| `Change feed` | `db/core/journal.giz`, `db/kv/local.giz` | The committed change feed for live queries, notifications, search and automations: the SQL journal's rows, and the KV engine's keys by revision (two engines share no storage) | `Change`, `ChangeFeed`, `Feed` |
| `HTTP server` | `web/app.giz`, `sdk/net/http.giz`, `sdk/net/tls.giz` | The one HTTP server loop: GizWeb serves, on the standard library server. A hosted app does not write a second loop | `HttpServer` |
| `TLS` | `sdk/net/tls.giz` | TLS for clients and servers, and its certificate chain and keys | `Tls`, `TlsStream`, `TlsServer` |
| `QUIC` | `sdk/net/quic.giz` | The QUIC transport (RFC 9000) under HTTP/3: endpoints, connections, streams and packet protection | `initialSecrets` |
| `Loss recovery` | `sdk/net/recovery.giz` | RTT estimation, loss detection timers and NewReno congestion control, for QUIC now and the GizOS TCP later | `newPath`, `probeTimeout`, `lossDelay` |
| `Build slots` | `tools/cli/slots.giz` | The machine's build admission: the slots file reader, the slot kinds and the local slots that a build holds | `slotWords`, `slotKind`, `localSlots`, `holdSlot` |
| `Store eviction` | `tools/cli/files.giz` | The one eviction policy of the machine store ($GIZLANG_CACHE): seven days unused, at most once a day | `pruneArtifacts`, `pruneEntries` |
| `Unit key` | `tools/cli/build.giz` | The key of a compiled program or unit in the store: its sources, the toolchain and the link recipe | `unitKey` |
| `Shared-cache signature` | `tools/cli/buildstore.giz` | The signature of a store entry that another machine may use (GIZLANG_SHARED_CACHE, GIZLANG_TRUSTED_KEYS) | `sharedMessage`, `signBuilt`, `verifyShared` |
| `Program link` | `tools/cli/build.giz` | Linking IR and objects into an executable for one target and profile | `linkParts`, `optimizedLink` |
| `SQL identifier` | `sdk/core/text.giz` | One SQL delimited identifier: the name quoted, with its embedded quotes doubled | `quoteIdentifier` |
| `Hex` | `sdk/core/text.giz` | Lowercase hexadecimal of bytes, and its strict decoder | `hexEncode`, `hexDecode` |
| `Aggregate names` | `model/sql/aggnames.giz` | Which SQL function names are aggregates: the parser, the binder and the catalog checks read them here | `isAggregate`, `isAggregateCall` |
| `Integer parsing` | `sdk/core/text.giz` | Strict decimal and radix integer parsing: each text is ok, invalid or overflow, never a guess | `parseI64`, `parseRadix` |
| `Date and time format` | `sdk/core/time.giz` | A time as text in a format string, and the reverse: formatTime and parseTime of the one time module | `formatTime`, `parseTime` |
| `HTTP date` | `sdk/net/http.giz` | The HTTP date of RFC 9110 (IMF-fixdate, RFC 850 and asctime): one writer and one parser | `httpDate`, `parseHttpDate` |
| `Expression SQL` | `model/sql/render.giz` | A syntax tree printed as SQL text of a dialect, with the values bound as parameters | `mutation`, `bound`, `boundMutation`, `expressionText`, `boundCondition` |
| `HTML text` | `sdk/format/html.giz` | The Html value, and the escaping of text and attribute values that every HTML writer shares | `Html`, `escape`, `unescape` |
| `HTML parser` | `browser/html.giz` | HTML bytes to a Document in one pass, and the serializer back to HTML | `documentSource`, `documentEncoding`, `serialize` |
| `CSS sheet` | `browser/css.giz` | CSS text to a Sheet: rules with their selectors, declarations and media conditions | `Declaration`, `Rule`, `declarations` |
| `CSS tokens` | `browser/syntax.giz` | CSS Syntax 3 tokens: the one tokenizer, and the token walks that the later stages share | `Token`, `tokenize` |
| `CSS selector` | `browser/selector.giz` | Selectors (Selectors Level 4) compiled once to flat parts, and matched against the document | `Selector`, `parseList`, `matches`, `query`, `matchesText` |
| `DOM` | `browser/dom.giz` | The document as flat columns of nodes and atoms, with the input edits and text steps of a page | `Edit`, `Step` |

<!-- /structure:concepts -->
