Project Structure

maho-storefront/
├── src/
│   ├── index.tsx              # Main Hono app — routing, caching, SSR
│   ├── api-client.ts          # Maho REST API wrapper
│   ├── page-config.ts         # Variant resolver (page.json → component selection)
│   ├── types.ts               # TypeScript type definitions
│   ├── content-store.ts       # KV abstraction layer
│   ├── asset-version.ts       # Cache-bust hash generation
│   ├── css/                   # CSS source files
│   │   ├── product.css        # Product page styles
│   │   ├── cart.css           # Cart & checkout styles
│   │   ├── account.css        # Account dashboard styles
│   │   └── ...
│   ├── js/
│   │   ├── app.js             # Stimulus application bootstrap
│   │   ├── stimulus.js        # Stimulus re-export
│   │   ├── api.js             # Client-side API helpers
│   │   ├── utils.js           # Utility functions
│   │   ├── template-helpers.js # DOM hydration utilities
│   │   ├── analytics.js       # Event tracking
│   │   ├── payment-methods/   # Payment adapter implementations
│   │   └── controllers/       # 19 Stimulus controllers
│   └── templates/
│       ├── Layout.tsx          # Base HTML layout
│       ├── Home.tsx            # Homepage template
│       ├── Product.tsx         # Product detail page
│       ├── Category.tsx        # Category listing page
│       ├── Cart.tsx            # Cart page
│       ├── Checkout.tsx        # Checkout flow
│       ├── Account.tsx         # Account dashboard
│       └── components/         # Component variant system
│           ├── product-display/
│           ├── cart/
│           ├── category/
│           ├── filtering/
│           ├── homepage/
│           ├── navigation/
│           ├── checkout/
│           └── ...
├── public/
│   ├── styles.css             # [generated] UnoCSS output
│   └── controllers.js.txt     # [generated] esbuild JS bundle
├── scripts/
│   └── generate-manifest.js   # Manifest generator
├── theme-output/              # [generated] Sync output cache
├── wrangler.toml              # Cloudflare Workers configuration
├── uno.config.ts              # UnoCSS + DaisyUI configuration
├── theme.json                 # Default theme design tokens
├── page.json                  # Default component variant config
├── stores.json                # Store → theme/config mapping
├── deploy.sh                  # Deployment script
└── package.json

Key Directories

src/ — Application Source

The core application. index.tsx is the entry point — a Hono app that handles routing, edge caching, and server-side rendering.

src/templates/components/ — Variant System

Organized by domain (product-display, navigation, cart, etc.). Each slot has:

• _manifest.json — variant definitions
• index.tsx — variant resolver
• VariantName.tsx — individual variant implementations

See Component Variants for details.

src/js/controllers/ — Stimulus Controllers

Client-side behavior via Stimulus.js. Controllers attach to server-rendered HTML using data-controller attributes. See Controllers for details.

src/css/ — Stylesheets

Component-specific CSS loaded as UnoCSS preflights. Most styling comes from DaisyUI classes and UnoCSS utilities — these files handle complex component layouts.

Configuration Files

File	Purpose
wrangler.toml	Cloudflare Workers config (KV bindings, env vars)
uno.config.ts	UnoCSS config (DaisyUI integration, theme tokens, preflights)
theme.json	Design tokens (colors, fonts, spacing, radii, shadows)
page.json	Component variant selection per page type
stores.json	Maps store codes to themes and page configs

Generated Files

File	Generated By	Purpose
public/styles.css	bun run build:css	CSS bundle
public/controllers.js.txt	bun run build:js	JS bundle
manifest.json	bun run manifest	Component metadata