Skip to Content
Build with FinquStorefrontNexus ThemeArchitecture

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

DirectoryPurpose
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 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