Building Scalable UI Architectures · Part 2
Modular Patterns in a Monorepo

In Part 1, I outlined a layered approach to frontend architecture that’s helped me scale multiple products, from seed-stage velocity to enterprise complexity.
But a clean architecture on paper isn’t enough. Once your team grows and features evolve in parallel, you need enforcement mechanisms. You need tooling that turns your ideal structure into modular, testable, cacheable units.
That’s where a tool like Turborepo can help.
Layered Architecture Recap
Let’s revisit the layers from the previous post:
- SDK Layer — Internal UI kit (pure presentation)
- Domain Layer — Feature-specific UI + behavior
- API/Logic Layer — Typed data access, hooks, error/loading logic
As your product scales, you’ll also build a supporting structure, including shared directories that live alongside those layers to maintain the system's coherence and developer-friendliness.
Here’s an example of how you can organize all of this modularly while maintaining consistency as your team grows:
packages/
sdk/ → UI components, design tokens
api/ → API clients and data-fetching hooks
hooks/ → Shared cross-cutting logic (e.g., useSound)
context/ → Global state (auth, theme, feature flags)
utils/ → Formatting, transforms, pure helpers
types/ → Shared TS types and guards
styles/ → CSS themes, global styles
test/ → Mocks, setup, and test utils
apps/
web-app/ → Main frontend app
app/ → App entrypoint (main.tsx, layout.tsx)
domain/
map/ → Feature-specific logic: map views, behaviors
context/ → App-only provides (session, layout state)
utils/ → App-only helpers (e.g., navigation utils)
types/ → App-only types
routes/ → Route configuration
test/ → App-specific test config
admin-panel/ → Internal dashboard
Each app apps/*owns its own routes/, domain/, local context/, types/, utils/, and tests/ folders as needed.
You can think of the apps/ layer as the final assembler, it composes and orchestrates all feature domains, shared packages, and app-specific concerns into a complete product experience.
Principles to Follow
To keep the repo scalable as you grow:
- Upward-only dependencies: Lower-level packages like
sdk,utils, ortypesshould never import fromdomainorapps. - Stable interfaces: Each package exposes only its public API. Internal modules stay internal.
- Monorepo atomicity: Everything runs on the latest version inside the repo, no semver required, just clear boundaries.
Here’s a quick guide to which packages can depend on which:
sdk/*— can import fromstyles,types,utilsapi/*— can import fromtypes,utilshooks/*— can import fromutils,typescontext/*— can import fromhooks,typesapps/*— can import from any package
❌
*sdk*should never import fromapps✅*app*is allowed to use presentation (*sdk*) and logic (*api*,*hooks*)
Why Turborepo?
Turborepo is a high-performance monorepo build tool that lets you:
- Enforce boundaries between packages (e.g., design tokens shouldn’t depend on feature logic)
- Speed up builds with caching and task pipelines
- Structure your app around your architectural layers
- Empower teams to build in parallel without stepping on each other
It’s not magic, just a smart way to treat packages and pipelines like first-class citizens.
Enforcing Structure with ESLint
You’ll eventually forget one of these rules. That’s fine. The linter won’t.
Using eslint-plugin-boundaries or eslint-plugin-importYou can catch invalid imports at dev time:
// .eslintrc.js
rules: {
'no-restricted-imports': [
'error',
{
paths: [
{
name: '@myorg/domain',
message: 'Do not import domain logic into shared packages like sdk',
},
],
},
],
}
You can also tag each package with a “layer” tsconfig.json to help IDEs and tooling recognize architectural boundaries.
Workflow Pipelines with turbo.json
Defining clear build pipelines is what keeps this structure fast and sustainable. Here’s an example of how to set up turbo.json to coordinate builds across packages:
{
"pipeline": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**"]
},
"lint": {},
"typecheck": {},
"test": {
"dependsOn": ["build"]
}
}
}
With this setup, changing sdk/ only triggers builds/tests for packages and apps that depend on sdk/. It’s cache-aware and graph-aware, so you waste zero cycles.
Example: Building a Feature the Right Way
Suppose you’re building two features: a Service Map and a Notifications panel.
Here’s how to organize the pieces:
apps/
web-app/
domain/
map/ → Map UI components
routes/
map.tsx → Route config for Map feature
admin-panel/
domain/
notifications/ → Notifications UI components
routes/
notifications.tsx → Route config for Notifications feature
Feature: Interactive Map
// apps/web-app/domain/map/Map.tsx
export function Map() {
// UI logic for rendering map
}
// packages/api/useMapData.ts
export function useMapData() {
// fetch map points, boundaries
}
// packages/utils/latLngToText.ts
export function latLngToText(lat: number, lng: number) {
return `${lat}, ${lng}`;
}
// packages/hooks/usePanToLocation.ts
export function usePanToLocation(mapRef: RefObject<Map>) {
// smooth pan-to behavior
}
// packages/types/Map.ts
export interface MapRegion {
id: string;
name: string;
coordinates: number[][];
}
// packages/sdk/ZoomControl.tsx
export function ZoomControl() {
// shared UI control
}
Feature: Notifications Panel
// apps/admin-panel/domain/notifications/NotificationsList.tsx
export function NotificationsList() {
// list UI
}
// packages/api/useNotifications.ts
export function useNotifications() {
// fetch and subscribe to notifications
}
// packages/hooks/useSound.ts
export function useSound(src: string) {
// plays a chime when notification arrives
}
// packages/types/Notification.ts
export interface Notification {
id: string;
type: string;
message: string;
timestamp: string;
}
// packages/sdk/Badge.tsx
export function Badge({ count }: { count: number }) {
return <span>{count}</span>;
}
Why This Matters
- Feature UI and logic live inside the app’s
domain/, keeping them close to the routes and easier to evolve. - Data-fetching hooks live in
packages/api/for easy reuse across apps (web, admin, mobile, etc.). - Helpers and utilities (like formatters, transforms) go in
packages/utils/orpackages/hooks/, no more duplicating logic across apps. - UI primitives like
<Badge />are centralized inpackages/sdk/for a consistent look and feel across the product. - Routes are defined in
apps/*/routes/, keeping navigation concerns separate from business logic.
Every layer has a distinct responsibility, which enhances clarity. This clarity simplifies onboarding, debugging, and scaling as your team expands. More importantly, it maintains modularity without being overly rigid
A Note on Testing
Every package and app has its test config, usually vitest.config.ts or jest.config.js
You can create a base for these configurations and extend it for consistency across the repo.
packages/
test/ → setup, test utils, mocks
apps/
web-app/
domain/
map/
__tests__/
MapView.test.tsx → test for specific view
Turborepo caches your test runs, so you’re only testing what’s changed. That makes a huge difference when you’re iterating fast across dozens of packages.
Final Thoughts
A clean folder structure is a good start.
But true scalability comes from modularity, with clear ownership, consistent contracts, and tooling that supports how teams build.
Combined with proper boundaries, type safety, and a solid design system, you can build a frontend that’s as elegant under the hood as it is on the screen.
This architecture reflects how I approach building frontend systems that are modular, maintainable, and scalable across teams. While I’ve applied similar ideas in previous roles, I’m continuing to evolve this model as I help shape new interfaces at Causely, a platform focused on uncovering root causes in complex systems.
If you’re exploring ways to organize your frontend layers more intentionally, or thinking about design systems and developer experience, I’d love to connect.