# Architecture Overview

Understanding how the Nexus theme is structured and how data flows through the system.

## Core Data Flow

1. **Request arrives** → Middleware detects locale and strips it from the URL path
2. **Dynamic router** resolves the URL path to a Finqu resource type and ID
3. **Template system** determines which renderer to use based on resource type
4. **Content delivery** → Either Puck template + visual blocks, or dedicated component (login, cart, etc.)

```
URL Request
    ↓
Middleware (locale detection)
    ↓
Dynamic Route Handler [app/(site)/[...slug]/page.tsx]
    ↓
Resource Resolver (resourceByPath API)
    ↓
Template Type Mapper
    ├─→ Templatable (product, category, page) → Puck Templates
    ├─→ System pages (login, cart, account) → Dedicated Components
    └─→ Not Found → 404
```

## Key Directories

| Directory      | Purpose                                                  |
| -------------- | -------------------------------------------------------- |
| `app/(site)`   | Public storefront pages with dynamic routing             |
| `app/(editor)` | Visual editor UI and template management                 |
| `blocks/`      | Puck visual editor components (product grid, hero, etc.) |
| `components/`  | React UI components organized by feature                 |
| `templates/`   | Resource-specific renderers (product, category, account) |
| `lib/`         | Utilities, queries, and configuration                    |
| `data/`        | Local storage for Puck configs (development)             |
| `.storefront/` | **Auto-generated** Puck editor configs (do not edit)     |

## Project Structure

```
theme-headless-nexus/
├── app/
│   ├── (editor)/               # Editor UI and API routes
│   │   ├── api/                # API endpoints for template/page save/publish
│   │   └── editor/             # Puck editor interface
│   ├── (site)/                 # Public storefront
│   │   └── [...slug]/          # Dynamic route for all URLs
│   ├── layout.tsx              # Root layout with providers
│   ├── page.tsx                # Home page
│   └── globals.css             # Global styles
│
├── blocks/                     # Puck visual components
│   ├── get-started.puck.tsx
│   └── product-grid/           # Complex block with edit/render separation
│       ├── product-grid.edit.puck.tsx
│       ├── product-grid.render.puck.tsx
│       └── shared.ts
│
├── components/                 # React UI components
│   ├── ui/                     # shadcn/ui primitives
│   ├── layout/                 # Header, footer, navbar
│   ├── product/                # Product-specific components
│   ├── cart/                   # Shopping cart components
│   ├── auth/                   # Authentication UI
│   ├── search/                 # Search interface
│   ├── editor/                 # Editor-specific UI
│   └── shared/                 # Shared utilities
│
├── templates/                  # Resource type renderers
│   ├── product-template.tsx
│   ├── products-template.tsx
│   ├── account-template.tsx
│   ├── cart-template.tsx
│   └── ...
│
├── lib/
│   ├── storefront.ts           # Finqu SDK client
│   ├── resource-resolver.ts   # URL to resource mapping
│   ├── template-types.ts      # Template type definitions
│   ├── locale.ts               # Locale utilities
│   ├── puck/
│   │   ├── config.tsx          # Puck editor configuration
│   │   └── storage.ts          # Template/page storage
│   ├── storage/                # Storage adapter (Redis/File)
│   ├── context-providers/      # React context providers
│   └── queries/                # GraphQL queries
│
├── data/                       # Local storage (dev only)
│   ├── layout/
│   └── page/
│
├── .storefront/                # Auto-generated Puck configs (DO NOT EDIT)
│   ├── puck.edit.config.tsx
│   └── puck.render.config.tsx
│
├── next.config.ts
├── tsconfig.json
├── package.json
└── README.md
```

## How It Works

### Dynamic Routing

The theme uses Next.js dynamic routes (`app/(site)/[...slug]/page.tsx`) to handle all storefront URLs. The route handler:

1. Extracts the locale from the URL (if present)
2. Calls the Finqu API to resolve the path to a resource
3. Determines the template type based on the resource type
4. Renders the appropriate template or component

### Template System

Templates define how different resource types are rendered. The system supports:

- **Templatable resources** (products, categories, pages) → Use Puck templates
- **System pages** (login, cart, account) → Use dedicated React components
- **404 pages** → Custom not found page

See [Templates](./templates) for more details.

### Storage

Templates and page configurations are stored in:

- **Development**: File-based storage in `data/` directory
- **Production**: Redis storage (when `UPSTASH_REDIS_REST_URL` is configured)

The storage system handles both draft and published versions of templates.

## Next Steps

- [Templates](./templates) - Learn how templates work
- [Blocks](./blocks) - Understand Puck blocks
- [Data Fetching](./data-fetching) - Learn about API integration