Layered Frontend Architecture
Small apps survive any folder structure. Large ones need clear boundaries so that a change in one place does not ripple everywhere. A layered, feature-first architecture is the most common answer senior engineers give in interviews. A layered frontend architecture is an application of separation of concerns.
1. Organize by feature, not by file type
// By type (breaks down at scale)
components/ hooks/ services/ utils/
// By feature (scales)
features/
checkout/
CheckoutView.tsx
use-checkout-view-model.ts
checkout.service.ts
checkout.types.ts
search/
...
shared/
ui/ // design-system primitives (Button, Modal)
lib/ // pure helpers (formatCurrency)
api/ // http client with auth, retries, timeouts
Everything a feature needs lives together, so it can be understood, tested, or deleted as a unit.
2. The layers
| Layer | Responsibility | Depends on |
|---|---|---|
| UI (views, components) | Render state, forward user intent | View models, shared UI |
| View model / hooks | UI state, derived data, commands | Services |
| Services / use cases | Business rules, orchestration | Repositories / API client |
| Repositories / API client | HTTP, storage, mapping DTOs to domain models | Nothing app-specific |
Dependencies point one way: inward/downward. A repository never imports a component, and a component never calls fetch directly.
3. Boundaries that pay off
- Single API client: base URL, auth headers, retries with backoff, timeouts, and error normalization in one place.
- DTO mapping at the edge: convert server shapes (snake_case, nullable fields) into domain models in the repository so the UI never sees raw API responses.
- Public feature API: other features import from
features/checkout/index.ts, not internal files. - Centralized config: environment variables read and typed in one module.
4. Cross-cutting concerns
Auth, logging, analytics, feature flags, and error boundaries are provided once (often via providers at the root or middleware in the API client) instead of re-implemented per feature.
5. Micro-frontends: when they make sense
Splitting an app into independently deployed micro-frontends helps when many teams need independent release cycles. It adds real costs: duplicated dependencies, cross-app state and routing complexity, and consistency issues. For one or two teams, a well-layered monorepo is usually better.
6. Signs Your Layered Frontend Architecture Is Working
- Deleting a feature folder removes the feature without breaking unrelated code.
- Swapping REST for GraphQL touches only repositories.
- View models and services can be unit tested without rendering.
