Skip to main content

​
Architecture

Use this page when you want the public system map before opening the deeper repository-native design docs. Loong is organized as a 13-crate Rust workspace with a strict dependency DAG. This page stays intentionally short: it explains the boundaries builders should preserve, not the full internal authoring trail. These boundaries describe the current public architecture contract, not a claim that every crate split or layer label is frozen forever. If the system evolves, the contract can evolve too, but it should do so explicitly and with review rather than through gradual undocumented drift.

​
Start Here If

​
What This Page Covers

  • the crate DAG and what each crate owns publicly
  • the layered execution model and the boundaries it protects
  • the usual starting point for common change types
  • the common architecture smells that signal a boundary problem
Publicly, the useful split is: a minimal base/runtime substrate, stable contracts, a governed kernel, a product/runtime layer, deterministic spec and benchmark rails, and the daemon delivery layer that turns those lower layers into runnable operator entrypoints.

​
Crate Roles

​
Layered Execution Model

The crate DAG is only half of the public architecture story. The runtime is also layered so governance and execution stay explicit.

​
Public Principles

  • governance-first execution
  • additive evolution for public contracts
  • small core, rich extension seams
  • no internal dependency cycles

​
What The Boundary Buys You

  • Policy stays in the real runtime path instead of becoming documentation-only intent.
  • New product surfaces can reuse the same governed execution model instead of inventing sidecar rules.
  • Specialization happens through packs, adapters, and integration lanes rather than repeated kernel rewrites.
  • Builders can reason about where a change belongs before they touch code.

​
Where Changes Usually Belong

​
Non-Negotiable Boundary Rules

  • Do not introduce dependency cycles.
  • Do not bypass kernel-governed capability, policy, and audit paths with shadow execution routes.
  • Prefer additive growth to breaking public contract rewrites.
  • Keep runtime-backed product surfaces on the same governed model instead of inventing one-off sidecar systems.
Those rules are intentionally strict for the current architecture posture. When maintainers decide the posture itself should change, the expectation is an explicit architecture update, not an exception that quietly becomes the new shape.

​
Common Architecture Smells

  • a new feature wants to talk around the kernel instead of through it
  • a product surface introduces its own private policy or audit logic
  • a crate starts absorbing domain behavior that belongs in adapters or packs
  • a contribution adds coupling across crates because the boundary feels inconvenient
  • a public contract is “simplified” by deleting explicit runtime truth
If a change smells like one of those, the architecture is usually telling you to reshape the contribution rather than pushing through the boundary.

​
Go Deeper