Add Frontend Architecture

---
name: add--frontend-architecture
description: Frontend architecture consultant for project structure, folder organization, feature boundaries, and scaling decisions. Framework-aware (React, Vue, Angular). Use when user asks about frontend folder structure, "components folder is a mess", "where should this go", over-engineering, slices, feature folders, or starting/refactoring a frontend project. Guides decisions only — does not implement (use add--frontend-development) or design UI (use ux-design).
---

# Frontend Architecture Consultant

<!-- uses:
- skill: add--frontend-development
- mention: add--backend-architecture
- mention: add--project-scaffolding
- mention: add--ux-design
- skill: add--frontend-architecture/references/angular.md
- skill: add--frontend-architecture/references/react.md
- skill: add--frontend-architecture/references/vue.md
-->

Guide structural decisions for frontend projects. Choose the **simplest** pattern that keeps the team productive as the project grows.

---

## Framework Detection

Detect first — each framework has a different opinion level about structure.

| Framework | Opinion | Skill role | Reference |
|-----------|---------|-----------|-----------|
| **Angular** | High (modules, DI, routing built-in) | Validate/optimize within Angular | `references/angular.md` |
| **Vue** | Medium (Composition API + Pinia, structure free) | Fill gaps Vue leaves open | `references/vue.md` |
| **React** | Low (almost nothing decided) | Define what React doesn't | `references/react.md` |

Detect via `package.json`, `stack-context.md`, or ask. For Svelte/Solid/etc., apply universal principles below.

---

## Decision Navigator

### Context Questions

1. **Scale** — Small (1-10 pages) / Medium (10-30) / Large (30+)
2. **Team size** — Solo (1-2) / Medium (3-5) / Large (6+)
3. **Component reuse** — Minimal / Moderate / Heavy (design system)
4. **Domain complexity** — Light (CRUD) / Moderate (multi-step flows) / Heavy (real-time, rich interactions)
5. **Framework** — Determines how much the skill must define

### Decision Matrix

| Context | Pattern | Why |
|---------|---------|-----|
| Small scale, solo dev, light domain | **Simple Component-Based** | Flat structure, fast to navigate, no ceremony |
| Medium scale, small-medium team, moderate domain | **Feature-Based** | Features co-located, scales well, easy to understand |
| Large scale (30+ pages, 6+ devs), heavy domain, complex feature interactions | **Feature-Sliced Design** | Formalized layers, strict boundaries; overkill for solo/small/CRUD |

**Over-engineering signals:** more folders than files; barrel files everywhere causing circular deps; `/shared` with 50+ unnavigable components; layers added "because architecture says so".

**Under-engineering signals:** flat `components/` with 80+ files; API calls inside buttons; state scattered across stores/components/URL; full-text search needed to find anything; week-long onboarding.

---

## Architecture Patterns

### Simple Component-Based

For small projects where anything more is overhead.

```
src/
  pages/         home.tsx, about.tsx, settings.tsx
  components/    header.tsx, footer.tsx, user-card.tsx     (flat)
  hooks/         use-auth.ts, use-users.ts                  (or composables/)
  lib/           api.ts
  types/         user.ts
  app.tsx
  routes.tsx
```

Rules: pages = route-level; components folder flat; no feature folders; direct imports fine.

**Graduate when:** `components/` exceeds 25-30 files.

### Feature-Based

For medium projects. Frontend equivalent of Vertical Slice — organize by business feature. See framework-specific reference for details.

```
src/
  features/
    auth/        components/  hooks|composables/  types.ts  index.ts
    products/    components/  hooks|composables/  types.ts  index.ts
    orders/      components/  hooks|composables/  types.ts  index.ts
  shared/
    components/  ui/          (design system primitives)
                 layout/      (header, sidebar, footer)
    hooks|composables/
    lib/         api.ts
    types/
  pages/         (thin, compose features)
  app.tsx
```

Rules:
- Features own their components, hooks, types
- Cross-feature imports go through `index.ts` public API only — never internal files
- `shared/` = truly reusable, domain-agnostic code only
- Pages are thin — compose features, no business logic

### Feature-Sliced Design (FSD)

For large projects with many devs and complex feature interactions.

```
src/
  app/         (global setup: providers, routing, styles)
  pages/       (route-level — combine widgets and features)
  widgets/     (complex UI blocks — combine features and entities)
  features/    (user interactions — forms, toggles, actions)
  entities/    (business objects — user, product, order)
  shared/      (infrastructure — UI kit, API client, utilities)
```

**Strict dependency rule:** `app → pages → widgets → features → entities → shared`. Each layer imports only from layers below. Never upward.

Within each layer, organize by **slice** (domain concept):

```
features/
  add-to-cart/      ui/  model/  api/  index.ts
  apply-discount/   ui/  model/  api/  index.ts
```

**Apply FSD when:** 6+ frontend devs, 30+ pages, complex feature interactions, strict boundaries needed. Skill's role is to decide *when* FSD fits and apply it pragmatically — not replicate the full spec.

---

## Universal Principles

| Principle | Rule |
|-----------|------|
| **Component roles** | Page (compose, no logic) / Feature (domain logic) / UI (presentational, props only) / Layout (structural). Never mix — buttons don't fetch, pages don't compute. |
| **Feature isolation** | Features import from `shared/` and self only. Cross-feature → through public `index.ts`. Need data from another feature → shared hook or data layer, never internal imports. |
| **State location** | Component state → in component. Feature state → feature store/hook. Server state → fetching lib cache. Global UI → app store. URL state → router params. Don't hoist higher than needed; don't globalize everything. |
| **Thin pages** | Pages set up layout, compose features, handle route params, set metadata. Never contain business logic, direct API calls, or complex state. |
| **Shared discipline** | Good: UI primitives, layout, API client, auth hooks, utilities, API types. Bad: feature components disguised as reusable, business logic, single-feature consumers. |
| **Barrel strategy** | DO at feature boundary (`features/auth/index.ts`). DON'T inside internals or as one mega-barrel of all shared (causes circular deps + bundle bloat). |

---

## When NOT to Use

- [ ] User asks how to **implement** a feature (routing, forms, data fetching) — use `add--frontend-development`
- [ ] User asks about **UI/UX design**, styling, components visuals — use `add--ux-design` / `frontend-design`
- [ ] User asks about **backend** structure or APIs — use `add--backend-architecture`
- [ ] User wants to **scaffold** a new project from scratch — use `add--project-scaffolding`
- [ ] Question is about a specific library's API — use Context7 docs

---

## Workflow

- [ ] Detect framework (package.json, stack-context.md, or ask)
- [ ] Assess context: scale, team size, component reuse, domain complexity
- [ ] Match to Decision Matrix; explain why alternatives don't fit
- [ ] Load framework-specific reference (`references/{react|vue|angular}.md`)
- [ ] Map the pattern to user's actual features and pages
- [ ] Address framework gap: React → define everything; Vue → fill gaps; Angular → validate/optimize