> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meow.style/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture
> How meow parses your code once and feeds every tool from a single in-memory model.
meow is one binary, but internally it's a set of sharply separated layers. The
design goal is **structural separation of side effects from computation**: only
the outermost layer reads the ambient host (environment, home directory, current
working directory); everything beneath it operates on values it was handed. That
discipline is what makes determinism, testability, and the single-parse pipeline
possible.
## The Parse-Once pipeline
In a conventional toolchain, your code is parsed many times: the runtime parses it
to execute, the linter parses it to analyze, the formatter parses it to reprint,
the type-checker parses it, the bundler parses it again. Five tools, five parsers,
five copies of your AST melting your CPU.
meow parses your code **exactly once** using the [Oxc](https://oxc.rs) parser and
keeps a single lossless model in memory. That one model serves every consumer:
A lossless tree that preserves every token and whitespace span — what the
**formatter** needs to reprint faithfully.
Scopes, bindings, and references built on top of the CST — what the **linter**
and **type-aware tooling** need.
TypeScript annotations are blanked in place (preserving byte positions, so no
source maps are needed) to produce the JavaScript the **runtime** executes.
These stages are modeled as **lazy, invalidatable queries**: a stage is computed
on demand and cached, and editing a file invalidates only what depends on it. The
formatter, linter, type-checker, runtime, and bundler all draw from this one graph
instead of re-reading your source.
meow uses Oxc for *all* parsing, semantic analysis, type-stripping, and JSX
transformation. The bundler (Rolldown) uses the same Oxc generation internally,
so there is never a second, divergent AST in the dependency graph.
## The execution model
meow runs on a tuned build of V8, embedded through `deno_core`. Execution is
**cooperative, single-threaded, and multi-isolate**:
```mermaid theme={null}
graph TB
subgraph OS_Thread ["Main OS Thread"]
T[Tokio LocalSet executor]
end
subgraph Isolates ["Isolates"]
M["Main Isolate
V8, !Send"]
W1["Worker Isolate 1
V8, !Send"]
W2["Worker Isolate 2
V8, !Send"]
end
T --> M
T --> W1
T --> W2
%% Styling
style M color:#FF4D9D,stroke:#fff,stroke-width:1px
style W1 color:#FF4D9D,stroke:#fff,stroke-width:1px
style W2 color:#FF4D9D,stroke:#fff,stroke-width:1px
```
V8 isolates are `!Send` — they can't move between OS threads. Rather than fight
that, meow embraces it: `node:worker_threads` workers and the test runner's
per-suite isolates are spawned as cooperative tasks on the **same** thread's Tokio
`LocalSet`. They interleave perfectly (think Vite's parallel bundling pipelines)
without the heavy context-switching of OS threads.
CPU-bound work that *should* leave the main thread — SHA-512 verification and
tarball decompression during installs — is offloaded to background OS threads, so
network I/O is never starved waiting on a hash.
## The crate map
meow is composed of focused crates, each isolating one concern. The only crate
permitted to read ambient host state is the CLI edge.
The command-line edge. Owns argument parsing, the omni-router, the terminal UI
helpers, and project-root discovery. **The only layer that reads host
environment variables.**
Reads `meow.config.json` and the user-owned `package.json`; generates the
git-ignored shadow `tsconfig` that editors and `tsc` consume.
The single Oxc pipeline: CST, semantic graph, and runtime IR as lazy,
invalidatable queries. The one parser entry point for the whole workspace.
V8 isolate orchestration, the event loop, runtime extensions, in-place
TypeScript stripping, and the determinism harness.
The single module resolver for the toolchain: ESM and CommonJS resolution,
content-addressed cache reads, and TypeScript source fallback.
The lockfile model, the global content-addressed cache, integrity
verification, and `node_modules` materialization.
Linting, formatting (via the Oxc code printer), and bundling (via Rolldown over
meow's own resolver).
Pure, deterministic dependency path-tracing — the engine behind the `why-*`
observability verbs.
A dependency-free terminal rendering engine: gradients, Bento panels, progress
bars, and structured diagnostics — degrading to plain text in pipes and CI.
## Floof & Teeth
Two design values, deliberately in tension:
Best-in-class, empathetic terminal UX. Errors arrive as structured panels with
the offending line and a caret, not raw stack traces. Spinners are paw prints.
Output is a pleasure to read — and collapses gracefully to plain text when piped.
Zero-overhead systems engineering. One parse, copy-on-write installs, OS-thread
offloading, kernel syscalls, and a fat-LTO single-codegen-unit release binary.
Speed comes from engineering, never from skipping correctness.
This duality is a real design rule in meow: a feature is only "done" when it is
both fast **and** delightful. Benchmarks are never won by dropping the SHA-512
supply-chain check or by re-parsing your code in a corner.
## Where to go next
The `strict-web` / `node-compat` split that shapes everything above the engine.
The harness that makes a bare run reproducible across machines.