Mandatory Patterns
How mukoko is built
Every Mukoko app follows these patterns. They are not optional — they ensure consistency, resilience, and maintainability across the entire ecosystem.
5-Layer Architecture
Mandatory layered component architecture that enforces separation of concerns from primitives to server pages.
- Shared primitives
- Domain composites
- Page orchestrators
- Error boundaries
- Server wrappers
Error Boundaries
Three layers of error isolation that prevent one failing section from crashing the entire page.
- Component-level
- Section-level (new)
- Route-level
- Global fallback
Observability
Structured logging, performance measurement, and error tracking with the [mukoko] prefix for grep-ability.
- Scoped loggers
- Performance timing
- Error tracking
- Trace IDs
Component Patterns
CVA variants, Radix UI primitives, cn() composition, and data attributes — the mandatory stack for every component.
- CVA variant system
- Radix + Slot polymorphism
- cn() composition
- data-slot attributes
Resilience
Netflix Hystrix circuit breakers, retry with exponential backoff, and fallback chains — prevent cascading failures.
- Circuit breaker (Hystrix)
- Retry + exponential backoff
- Fallback chains
- Timeout wrappers
Lazy Loading
TikTok-style sequential mounting — one section at a time through a FIFO queue, with memory pressure monitoring.
- Sequential mount queue
- IntersectionObserver
- Memory reclaim (1500px)
- useMemoryPressure hook
AI Safety
Input validation, prompt injection detection, and rate limiting — mandatory for every Claude/Shamwari integration.
- Slug + input validation
- Prompt injection detection
- Sliding-window rate limiter
- Allowlist validation
Chaos Testing
Netflix chaos engineering — inject random errors and latency to verify circuit breakers and error boundaries work.
- Error injection
- Latency injection
- Chaos middleware
- Disabled by default
These patterns are enforced across all Mukoko apps: weather, news, nhimbe, super app, and shamwari. Install components from this registry — do not copy-paste or create parallel libraries.