Skip to content

5-Layer Architecture

Every Mukoko app enforces a strict 5-layer component hierarchy. Components import from the layer below, never sideways or upward. This ensures isolation, testability, and prevents cascading failures.

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 + Loading States components/section-error-boundary.tsx
L5 Server Page Wrappers app/[route]/page.tsx

Imports flow downward only.

Path: components/ui/

Foundational UI components from this registry — Button, Input, Card, Badge, etc. Installed via the shadcn CLI. Never import from higher layers.

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",
},
size: {
default: "h-9 px-3",
sm: "h-8 px-3",
},
},
defaultVariants: { variant: "default", size: "default" },
}
)

Path: components/weather/, components/reports/

Feature-specific components that compose Layer 1 primitives into domain-relevant UI. A WeatherCard combines Card + Badge + Progress from the registry.

components/weather/forecast-card.tsx

Path: components/landing/, components/dashboard/

Compose Layer 2 components into full page sections. Orchestrators NEVER hardcode rendering logic — they import and arrange domain composites.

components/dashboard/weather-dashboard.tsx

Layer 4: Error Boundaries + Loading States

Section titled “Layer 4: Error Boundaries + Loading States”

Path: components/section-error-boundary.tsx

Every section gets wrapped in a SectionErrorBoundary. If a chart crashes, only that section shows an error — the rest of the page continues working. This is mandatory.

components/dashboard/safe-dashboard.tsx

Path: app/[route]/page.tsx

Next.js App Router page.tsx files. Handle SEO metadata, data fetching, and pass props down to the orchestrator. These are React Server Components by default.

app/dashboard/page.tsx
async function getWeatherData() {
// Server-side data fetching
const res = await fetch("https://api.mukoko.com/weather", {
next: { revalidate: 900 }, // 15-minute cache
})
return res.json()
}
  • Components import from the layer below, never sideways or upward
  • Each component is a standalone file — independently installable via the registry
  • Page orchestrators NEVER hardcode rendering logic — they compose imported components
  • All colors and styles come from CSS custom properties in globals.css
  • SectionErrorBoundary wrapping is mandatory for every page section
  • Server components by default — add “use client” only when using hooks or event handlers