Technical stack and execution architecture

Architecture objective

Deliver a fast brand site focused on content, SEO and marketplace conversion, while preserving the ability to add a CMS, more products or proprietary commerce later without rebuilding the digital identity.

1. Decision principles

Six principles govern the architecture:

1. Speed of execution — few dependencies and minimal system administration.
2. Performance by default — send HTML for content and JavaScript only where interaction requires it.
3. Native SEO — make metadata, structured data, clean URLs and sitemaps part of the foundation.
4. One product source of truth — keep validated Gold facts in one typed record.
5. Progressive complexity — add a CMS, backend or checkout only in response to proven needs.
6. Portability — keep business and content layers independent from hosting and commerce providers.

2. Initial stack

Astro + TypeScript + Tailwind CSS
Astro Content Collections / Markdown / MDX
React islands when necessary
GitHub + Netlify
Google Tag Manager + GA4 + Search Console

Why Astro

The target is primarily a marketing and editorial site: homepage, Gold, origin, taste, recipes, articles, about and purchase-path pages. Astro can pre-render these pages as HTML, keeps client-side JavaScript low and supports structured content without requiring a full application runtime.

TypeScript and Tailwind CSS

TypeScript protects the product model, claims and component contracts. Tailwind accelerates consistent responsive implementation. Both are implementation tools; neither should leak unnecessary complexity into content management.

React as islands only

React is reserved for isolated interactive needs such as a taste selector, product comparison or dynamic marketplace component. Static sections remain Astro components and HTML.

3. Content and product data

Astro Content Collections provide the initial data layer for products, articles and recipes. Markdown or MDX remains versioned with the code, validated at build time and available to previews.

The Gold schema should include identifiers, names, origin, category, formats, sensory profile, uses, product image, marketplace destination, SEO fields and claim references. Each regulated or commercial claim also carries an internal status such as confirmed, pending, excluded or expired.

slug: gold
origin: Tunisia
region: Mahdia
regionStatus: pending
marketplaceUrl: https://example.com
claims:
  - id: single-origin
    status: confirmed

The publication layer must never turn a pending field into marketing copy.

4. CMS decision

No CMS is required at launch because the content volume and contributor group are limited, Git already provides history and review, and a CMS would introduce authentication, hosting, maintenance and modelling work before the editorial workflow proves that it needs them.

A CMS can be introduced later behind the same content model when non-technical publishing becomes frequent. Astro remains the frontend; only the content adapter changes.

5. Hosting and rendering

Netlify is selected for Git-based builds, deploy previews, atomic production releases, CDN delivery and optional functions. It avoids VPS administration and fits the initial Astro workflow better than building a broader infrastructure layer.

Netlify is not a business dependency. Environment access, commerce links and content data remain abstracted so another static host or CI platform can replace it.

Pages are statically generated by default. Server functions or client-side requests are introduced only for a real dynamic requirement such as secure form processing, inventory lookup or a commerce API.

6. Commerce architecture

V1 — external marketplace

The first version sends qualified visitors to a marketplace. A local route such as /buy/gold should own the outbound destination, allowing analytics and provider changes without editing every page.

Commerce adapter

Components consume a neutral commerce interface rather than a marketplace-specific URL. The adapter can initially return one external link and later connect to Shopify or another engine.

V2 — possible Shopify integration

Shopify becomes relevant only when direct-to-consumer volume, margins, operations and customer ownership justify checkout, catalogue synchronisation, orders, payments and fulfilment. Starting with Shopify would centre the architecture on commerce before that need exists.

WordPress/WooCommerce, Next.js, Strapi, a SQL database, authentication and a VPS are also excluded from the MVP because they solve requirements the initial site does not have.

7. Media, fonts and SEO

Use responsive image generation, explicit dimensions, modern formats, lazy loading below the fold and meaningful alternative text. Self-host a limited font set or use system fallbacks to avoid blocking rendering and unnecessary third-party calls.

Every page receives a unique title and description, canonical URL, social metadata and appropriate structured data. Generate sitemap and robots files, preserve semantic heading order and maintain internal links between product, origin, recipes and articles.

8. Analytics and consent

GTM can centralise tags, GA4 measures the agreed events and Search Console monitors indexing and queries. The initial event model includes product views, origin and recipe engagement, marketplace clicks and conversion-path diagnostics.

Consent must reflect the tags actually deployed. Non-essential analytics should not run before the required consent in markets where this applies. The system must remain usable when consent is refused.

9. GitHub and environments

• Local: authoring, component development and automated checks.
• Preview: one immutable Netlify preview per pull request or reviewed branch.
• Production: deployment only from the approved production branch.

Environment variables store deployment-specific public endpoints and server-side secrets. Secrets never enter Markdown, client bundles or the repository.

The workflow is: branch → checks → preview → content/visual review → merge → production deployment. Production should be reproducible from Git rather than from manual server edits.

10. Quality gates

Required checks cover a clean production build, content-schema validation, broken links, metadata, critical navigation, marketplace routing, responsive layouts, accessibility basics and page performance. Linting and formatting keep TypeScript, Astro and styles consistent.

11. Proposed repository structure

src/
  components/
  content/
    products/
    articles/
    recipes/
  layouts/
  pages/
  styles/
  lib/
    commerce/
    analytics/
public/

The logical flow remains:

validated content → Astro build → static pages → Netlify CDN
                                      ↘ commerce adapter → marketplace

12. Evolution path

V1 — digital presence

Astro, Tailwind, Content Collections, Netlify and an external marketplace.

V2 — business editing

Keep Astro and Netlify; add a CMS behind the existing schemas when publishing frequency and ownership require it.

V3 — possible DTC

Keep the brand frontend; extend the commerce adapter to Shopify or another engine and add server capabilities only where required.

13. Stack summary

Layer	Initial choice	Possible evolution
Framework	Astro	Retain Astro
Language	TypeScript	Retain TypeScript
Styling	Tailwind CSS	Retain or evolve tokens
Interactivity	React islands	Add islands only as needed
Product/content	Content Collections + MDX	CMS or API adapter
Hosting	Netlify	Interchangeable static platform
Commerce	Marketplace	Shopify or another engine
Backend/database	None	Add only for demonstrated needs
Analytics	GTM + GA4 + GSC	Retain with governed consent

14. Validation criteria and final decision

The architecture is valid when it produces fast, indexable pages; maintains one product truth; creates simple previews and reproducible deployments; requires little maintenance; supports easy publishing and marketplace replacement; and permits a future CMS or commerce engine without rewriting the frontend.

Final decision: Astro + TypeScript + Tailwind CSS + Content Collections/MDX + optional React islands + GitHub + Netlify + GTM/GA4/Search Console. Transaction remains external for the MVP.

The principle is maximum simplicity now, deliberate evolution later.

Official technical references

• Astro documentation
• Astro Content Collections
• Astro React integration
• Tailwind CSS with Astro
• Astro on Netlify
• Netlify deploy overview