Frontend Layered Architecture

Frontend Layered Architecture

Overview

Frontend directory structures should not collapse into “pages and everything else.” Type-revealing but role-ambiguous folders such as components, hooks, models, utils, and shared can absorb all code. This skill does not exist to force a large architecture. It exists to prevent business rules, API calls, URL state, and similar logic from unconsciously leaking into inappropriate folders during implementation.

Code should be separated into layers by role, dependency, external data boundary, and orchestration responsibility. Lower-level code must not be made aware of higher-level context.

This skill does not enforce a specific methodology such as Feature-Sliced Design or Vertical Slice Architecture. Type-based, feature-based, domain-driven, and other directory structures can all be valid. What matters is whether roles and dependency direction are clear within the structure the project has chosen, whether external data contracts are isolated, and whether code responsibilities and frontend-owned domain logic are managed effectively.

In an existing project, treat architecture as intentional only when it is documented, user-approved, or consistently recognizable through role, dependency, and Data boundaries. Otherwise, apply this skill's baseline to new and changed code instead of treating repeated placement as authority.

Common Foundation

If the project already uses layer terminology, prefer the project’s terms. Use the terms below only when there is no existing terminology, or when explaining structure. These abstract layer names are not default directory names; do not convert End-User, Domain, Shared, or Data into folders unless the user explicitly selected those names.

flowchart TB
  End-User --> Domain
  Domain --> Shared
  End-User --> Data
  Domain -. schemas/types by default .-> Data

These abstract layers are the minimum units for designing a sound frontend structure. Real projects may split them further, but this means at least four concepts are needed. That is why they are abstract layers.

Minimum guards:

• Layer names are abstract concepts, not required folder names.
• Shared is determined by code-level independence, not by generic names or absence of domain words. For example, ProductCard can be Shared if it only renders injected props, while a generic-looking buildSearchParams is not Shared if it knows router state, API request parameters, store state, or business rules.
• A general-purpose wrapper around a browser, router, form, or other library primitive can remain Shared when application-specific state, policy, and actions are injected. Judge the application context the code knows, not the package it imports.
• Data means a boundary the frontend consumes like externally-owned code; it does not mean the file must be physically external or written by another team. For example, OpenAPI-generated client/schema code and manually written API endpoint/schema code are both Data when the frontend consumes them as external contracts.
• Domain-to-Data access defaults to schemas/types only because declarative data fetching (e.g., useQuery-style APIs) keeps Data execution, caching, and synchronization in End-User UI orchestration. Do not replace this frontend default merely because another language or framework commonly uses a different direction. Follow another direction only when documented or approved project rules establish it, a consistently recognizable existing architecture already uses it, or the user explicitly decides it.
• Judge which project modules Data may depend on from its actual implementation instead of assigning one universal inward dependency rule.
• Even within the same abstract layer, dependency validity depends on role and responsibility. For example, if a project maps both features and widgets to Domain, features may still be forbidden from importing UI orchestration in widgets.
• When a project has documented or approved folder roles, use those roles first. Map them to abstract layers only to check whether responsibility or dependency direction is being violated; do not replace approved roles with current file names, sparse folders, or polluted usage.

Purpose Router

Classify the user’s purpose in one sentence, then read the first matching document. Do not use this file as a substitute for the routed document.

Routing rules:

• Choose the document by the user’s actual purpose, not by the first architecture keyword you notice.
• If a request has multiple purposes, route to the purpose that controls the next user-visible action.
• If the agent is about to add or change tool-based enforcement of frontend architecture rules, read enforcing-rules.md even when the user did not request enforcement or architecture is not the session's primary purpose.
• After reading the routed document, check whether it directly answers the user’s purpose. If not, say what is missing and route to the next required source instead of pretending the skill contains the answer.
• In existing codebases, read brownfield.md for both structure decisions and user-requested structure changes. Do not treat a request for a new directory or layer structure as greenfield work.
• For broad existing project audits or evaluations, read brownfield.md first, then check only the Common Mistakes table in best-practices.md as a secondary checklist. Do not apply examples as templates or override project-specific rules.
• For specific placement/import decisions or implementation work, do not read best-practices.md by default.