Storefront

Stack: Astro (SSR) + Preact islands + Tailwind. Deployed to Cloudflare (wrangler.toml).

This is the public online store a tenant’s customers browse and buy from. It’s the newest of the four applications and is not yet documented in the API’s own REFERENCE_PROJECT.md, so this page is currently the most complete reference for it.

Theming

Each website has a theme_key, currently electronics (default) or organics. Theme selection switches a data-theme attribute at the root, and every visual token is a CSS custom property, not a Tailwind config value:

• src/assets/styles/theme.css: Electronics tokens (cool graphite neutrals, amber-orange accent, near-sharp corners: --radius-sm: 4px, --radius-md: 6px).
• src/assets/styles/theme-organics.css: Organics overrides, scoped under :root[data-theme='organics'] (warm sage neutrals, deep green accent, soft rounded corners: --radius-lg: 32px on hero elements).

Token families: --color-* (ink, body, muted, bg, surface, surface-sunken, border, border-strong, accent + hover/ink/soft, on-accent, sale + soft, success + soft, whatsapp), --radius-*, --text-*, --space-*, --shadow-*.

The two themes aren’t just recolored. Some components branch structurally on themeKey === 'organics'. For example Header.astro renders two genuinely different layouts: Organics is a centered-wordmark header with a left category nav (hover flyout showing featured products); Electronics is logo-left/search-center/cart-right plus a second row with a “Browse Categories” dropdown and Home/Shop/About/Contact links. ProductCard.astro only renders its unit-badge seal on Organics.

Tenant-customizable vs. fixed tokens

src/lib/theme.ts documents which tokens a tenant can actually change via branding settings and which are fixed by the theme itself:

• Tenant-customizable: primary_color → --color-accent, accent_color → --color-accent-ink/--color-accent-soft, background_color → --color-bg.
• Deliberately not exposed to tenants: ink/body/muted, surface/surface-sunken, and secondary_color (unmapped). These stay theme-controlled to keep the design coherent.

Content model

The homepage (src/pages/index.astro) is CMS-configurable via a homepage_sections array, supporting types: hero, trust_grid, story, organic_statement, perk_row, featured_products, featured_categories, brand_grid, banner, latest_products, plus an always-on category grid/list and a second banner appended below whatever’s configured.

Key components: Header, Hero (two-column, carousel visual, Organics-only price callout card), ProductCard, TrustGrid, PerkRow, StorySection (Electronics) / OrganicStatement (Organics), FeaturedCategories, BrandGrid, CategoryGrid, CategoryList, Banner, FlashSaleBanner, ProductCarousel, Footer.

Routes

/products, /products/[slug] (gallery + purchase panel + specs + bundle contents), /categories, /categories/[slug], /cart, /checkout, /orders/[receipt], /track-order, /[slug] (generic content pages: About/FAQ/Contact via PageBody/ContactPage/FaqPage), 404.

cart and checkout both redirect to / when branding.cart_enabled === false: a disabled cart must not leave a reachable, fully-functional order path with no navigation leading to it.

Marketing/SEO/tracking changes need the in-app guide updated too

If you touch storefront tracking (src/lib/tracking.ts), marketing/SEO settings fields, structured data, sitemap, or robots behavior, update dg_smart_pos_frontend/src/modules/Website/components/MarketingGuideModal.vue in the same change. See Conventions for why this is a hard rule and not optional polish.

Designing storefront UI changes

The two themes are also modeled in Figma (homepage fully built for both, screenshot-verified against these components) so UI adjustments can be iterated on visually before being implemented in code. Ask in the team channel for the current Figma file link if you’re picking up storefront UI work.

Local setup

pnpm install
pnpm run dev
pnpm run build