> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mzizi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Application layers

> The five-layer component hierarchy an application built on Mzizi enforces, and why imports only ever flow downward.

<Warning>
  **These five layers are not the helix.** This page describes how to structure the components
  *inside one application*. [The DNA helix](/architecture/overview) describes where a component
  sits in the *design system*, with nodes numbered N1 to N8 and rungs N9 to N12. Two different
  models, two different numberings — never quote a count from one while describing the other.
  The `L` prefix below is local to an application.
</Warning>

Every application enforces a strict five-layer hierarchy. A component imports from the layer
below it, never sideways and never upward. That is what makes a section testable in isolation
and stops one failure cascading.

| Layer | Name | Path |
| - | - | - |
| L1 | Shared primitives | `components/ui/` |
| L2 | Domain composites | `components/weather/`, `components/reports/` |
| L3 | Page orchestrators | `components/landing/`, `components/dashboard/` |
| L4 | Error boundaries and loading states | `components/section-error-boundary.tsx` |
| L5 | Server page wrappers | `app/[route]/page.tsx` |

> Imports flow downward only.

## L1 — shared primitives

`components/ui/`

Foundational components installed from the registry — button, input, card, badge. They never
import from a higher layer, and they hold no business logic.

```tsx theme={null}
// components/ui/button.tsx
const buttonVariants = cva("inline-flex items-center justify-center …", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground",
      outline: "border-border bg-input/30",
    },
  },
  defaultVariants: { variant: "default" },
})
```

## L2 — domain composites

Components that know about your domain — a weather card, a report row — built entirely from
L1 primitives. This is the first layer allowed to know what the application is about.

## L3 — page orchestrators

Sections that arrange L2 composites into a region of a page. They arrange; they do not
implement.

## L4 — error boundaries and loading states

Every L3 section is wrapped. A crashing chart shows a fallback where the chart was, and the
rest of the page keeps working.

```tsx theme={null}
<main className="flex flex-col gap-6">
  <SectionErrorBoundary section="Weather overview">
    <WeatherOverview />
  </SectionErrorBoundary>

  <SectionErrorBoundary section="Activity feed">
    <ActivityFeed />
  </SectionErrorBoundary>
</main>
```

See [error boundaries](/patterns/error-boundaries).

## L5 — server page wrappers

`app/[route]/page.tsx`. Data fetching and the route-level composition. This is where the
network lives, so it is the layer where a failure is expected rather than exceptional.

## Why downward only

The rule is what buys the isolation. An L1 button that imported an L3 dashboard section would
make the button untestable, un-installable into another project, and capable of taking a page
down from inside a design system component. Each of those is a real failure mode; the import
direction removes all three at once.

<Note>
  The registry's old design portal had an interactive demonstration of all five layers, where
  each section was wrapped in a `SectionErrorBoundary` and you could trigger a crash to watch
  the isolation hold. It went with the registry's app on 2 October 2026, and no live demo
  replaces it. To see the isolation, wrap two sections of your own app and throw in one.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.