# Component Architecture

This file defines how code should be organized in `shop-starter`.

## Goals

The architecture should optimize for:
- reuse
- performance
- predictable growth
- easy cloning for a new shop
- separation of concerns

---

## 1. Layer map

### `app/`
Use for:
- route files
- route-level data composition
- API route handlers
- metadata

Do not use `app/` for:
- giant inline UI trees
- reusable visual components
- deep business logic

### `components/layout/`
Use for:
- header
- footer
- page container
- global layout wrappers

### `components/sections/`
Use for:
- homepage sections
- archive shell
- product detail sections
- cart page section
- checkout page section
- wishlist page section

Section files represent page-level blocks, not tiny atoms.

### `components/ui/`
Use for:
- buttons
- inputs
- cards
- sliders
- pagination
- quantity stepper
- reusable micro-patterns

UI components should be reusable and intentionally scoped.

### `lib/`
Use for:
- config
- fetch clients
- Store API client/session helpers
- content adapters
- runtime state adapters
- shared utilities

### `types/`
Use for:
- shared storefront domain models
- cross-layer data contracts

### `wordpress/`
Use for:
- reusable WordPress / Woo plugin integration code only

---

## 2. Data flow rules

Preferred flow:
1. fetch from WP route or Woo Store API
2. normalize in `lib/`
3. map to shared domain type
4. pass narrow props to sections/UI
5. render

Do not:
- pass giant raw backend payloads deep into UI
- mix normalization logic into presentational components

---

## 3. Route file rules

Route files should stay thin.

They may:
- read params/search params
- fetch multiple data sources
- compose sections
- handle not-found behavior

They should not:
- contain huge repeated JSX
- contain duplicated mapping logic
- contain direct Woo session orchestration if shared helpers already exist

---

## 4. Server-first rendering

Pages and sections should stay server-rendered whenever possible.

Good server responsibilities:
- homepage content
- archive content
- product content
- initial cart view
- initial checkout state

Good client responsibilities:
- cart mutation buttons
- quantity controls
- wishlist buttons
- interactive checkout controls
- sliders

---

## 5. Public starter interfaces

These files act as high-level entry points:
- `lib/starter-data.ts`
- `lib/config.ts`
- `lib/wordpress-client.ts`

These files should stay small and stable.
Heavy logic should live behind them in focused modules.

---

## 6. Avoid god files

Avoid rebuilding giant files that do all of this at once:
- content fetching
- cart logic
- checkout logic
- runtime session logic
- mapping
- formatting

If a file starts covering too many responsibilities:
- split it
- keep the public interface stable

---

## 7. Naming rules

Name files and components by responsibility.

Good examples:
- `featured-products-section.tsx`
- `latest-categories-section.tsx`
- `product-purchase-panel.tsx`
- `storefront-content.ts`
- `woo-store-client.ts`

Bad examples:
- `helpers2.ts`
- `final-data.ts`
- `wrapper.tsx`
- `shop-thing.ts`

---

## 8. Mutation boundaries

All cart and checkout mutations should flow through shared lib helpers.

Do not duplicate:
- cart token handling
- nonce handling
- auth retry behavior
- checkout update orchestration

This logic belongs in one reusable shared layer.

---

## 9. Documentation coupling

If architecture changes meaningfully:
- update `AGENTS.md`
- update this file if structural guidance changed
- update Figma docs if the design implementation workflow changed

The starter should not drift into undocumented behavior.