Marketing site & landing page

The public marketing site lives in apps/marketing/ and is driven by a single config file: apps/marketing/src/landing.config.ts. You customize copy, theme, sections, SEO, and navigation there; the pricing page pulls live recurring products from your database at build time.

How it works

Here is how a page request flows from config to rendered HTML, and where pricing data joins the build.

Piece	Role
`landing.config.ts`	Brand, navigation, SEO defaults, theme preset, pricing display options, social links, legal placeholders
`sections/home.ts`	Ordered list of homepage sections (hero, splits, FAQ, etc.)
`Layout.astro`	Shared chrome, theme CSS variables, header/footer, GDPR, analytics islands
`loadPlansForBuild`	Fetches `publicProducts` (recurring) when the backend is reachable at build time; otherwise uses config/env fallback
`mapGraphqlPlan.ts`	Maps GraphQL products → marketing card shape; filters `is_default` products off the pricing page

📖 See also: Billing architecture for how products, checkout, and subscriptions relate to what visitors see on /pricing.

The config file

Almost everything marketing-specific is declared in apps/marketing/src/landing.config.ts. Treat it as your launch checklist — the file header lists pre-production SEO and legal tasks.

export const landingConfig: LandingConfig = {
  organization: { name: "PulseOS", tagline: "..." },
  siteUrl: SITE_URL,
  assets: { logo: "/brand/logo-mark.svg", ogImage: "/og/default.svg", ... },
  theme: SAAS_THEME_PRESET,
  navigation: { primaryLinks, headerCta, footerLinks, announcement, copyright },
  seo: { defaultTitle, defaultDescription, keywords, ogImage, twitterSite, structuredData },
  pages: { home, pricing, contact, legal },
  pricing: { billingToggle, enterpriseCta, onBuildFetchFailure },
  contact: { provider: "mailto", mailto: { email, subject } },
  legal: { companyName, website, contactEmail, jurisdiction, effectiveDate },
  sections: HOME_SECTIONS,
  social: { links: [...] },
  analytics: { enabled: true },
};

SITE_URL resolves from APP_URL or PUBLIC_SITE_URL at build time (apps/marketing/src/config/landing/siteUrl.ts). Canonical URLs, Open Graph links, and the sitemap all depend on it.

Set APP_URL to your real production domain before launch. A wrong value produces incorrect canonicals and sitemap URLs even if the site looks fine in the browser.

Theme

The marketing site uses a token-based theme separate from the portal MUI theme. Colors, radii, fonts, layout spacing, and shadows are defined in apps/marketing/src/config/landing/theme.ts and compiled to CSS variables at runtime via buildLandingThemeCss(). Pick a preset in landing.config.ts:

import { SAAS_THEME_PRESET } from "./config/landing/presets/saas";
// or FINTECH_THEME_PRESET, AI_THEME_PRESET

theme: SAAS_THEME_PRESET,

Customize a preset by spreading DEFAULT_THEME and overriding tokens (see presets/saas.ts). Light / dark / system is handled client-side. The footer theme selector writes marketingThemeMode to localStorage and sets data-landing-theme on document.documentElement. GDPR cookie UI and pricing cards read the same active tokens, so they follow the selected mode automatically.

Homepage sections

The homepage is a ordered array of typed sections. Define them in apps/marketing/src/config/landing/sections/home.ts and pass the export to sections in landing.config.ts.

`type`	Component	Typical use
`hero`	`Hero.astro`	Top-of-page headline, CTAs, optional image/video
`productShowcase`	`ProductShowcase.astro`	Screenshot + feature blurbs
`split`	`SplitSection.astro`	Two-column story with icon or image
`featureGrid`	`FeatureGrid.astro`	Icon grid of capabilities
`logoCloud`	`LogoCloud.astro`	Customer or integration logos
`stats`	`Stats.astro`	Numeric proof points
`testimonials`	`Testimonials.astro`	Quotes
`faq`	`Faq.astro`	Question / answer list
`closingHero`	`ClosingHero.astro`	Final conversion band

Minimal hero example:

{
  type: "hero",
  id: "hero",
  variant: "centered",
  headline: "Run your SaaS with confidence",
  subheadline: "Billing, teams, and admin in one place.",
  primaryCta: {
    label: "Start free",
    href: "/signup",
    ctaId: "hero-primary",
    variant: "primary",
  },
},

Each section needs a stable id (used for analytics data-marketing-section attributes). CTAs use CtaLink.astro, which emits data-marketing-event="landing_cta_clicked" for tracking. Icons in split/feature sections use names resolved by LandingIcon.astro (credit-card, shield-check, etc.). Images in public/ are referenced with paths like /brand/hero-screenshot.svg; resolvePublicAsset() handles base URL when needed.

SEO & discovery

Per-page SEO and indexable static routes both come from landing.config.ts → pages.*, plus global seo defaults. Blog URLs are separate — Postgres is the SSOT for articles, pillars, and series.

Concern	SSOT	Notes
Static page metadata + paths	`landing.config.ts` → `pages.*`	Titles, descriptions, canonical paths, `noindex`
Static page routes	`apps/marketing/src/pages/`	Must match a `pages.*` entry
Sitemap + llms.txt (static half)	`pages.*` via `discovery-static-pages.json`	Emitted at marketing build; backend merges at regen
Blog URLs	Postgres (`BlogArticle`, `BlogPillar`, `BlogSeries`)	Dynamic; regenerated on publish/update/delete + scheduler. Blog index canonical is `BLOG_INDEX_PATH` (`/blog/`); `/blog` 301s there.

Field	Where	Effect
`seo.defaultTitle` / `defaultDescription`	Global	Fallback brand strings
`seo.keywords`	Global	Default meta keywords
`seo.ogImage`	Global	Default Open Graph image path
`seo.twitterSite`	Global	`twitter:site` handle (e.g. `@pulseos`)
`seo.structuredData`	Global	SoftwareApplication JSON-LD on home
`pages.home.title` / `description` / `path`	Per page	Home `<title>`, meta description, canonical
`pages.pricing.*`	Per page	`/pricing/` SEO
`pages.contact.*`	Per page	`/contact/` SEO
`pages.about.*`	Per page	`/about/` SEO
`pages.legal.*`	Per page	Privacy, terms, licenses

Document title format: Page title · Site name unless the page title equals the organization name (home).

const seo = buildSeo(landingConfig.pages.pricing, landingConfig);

Set noindex: true on a PageSeoConfig to exclude a page from sitemap and llms.txt.

Adding a static marketing page

Add an entry under pages.* in landing.config.ts (extend PagesConfig in types.ts if you add a new key).
Create a matching src/pages/.../index.astro that calls buildSeo(landingConfig.pages.<key>, landingConfig).
Run make build module=marketing so discovery-static-pages.json updates.
Discovery regen runs on backend startup (when marketing.staticPath is set), on blog publish/update/delete, or on the scheduled tick.
Verify /sitemap.xml and /llms.txt on APP_URL.

Header (SiteHeader.astro) reads navigation.primaryLinks and navigation.headerCta from config. Footer (SiteFooter.astro) reads navigation.footerLinks, navigation.copyright, and social.links. Announcement bar — toggle with navigation.announcement.enabled and set text + optional href. Social links are plain labeled anchors (opened in a new tab):

social: {
  links: [
    { platform: "twitter", href: "https://twitter.com/yourbrand", label: "Twitter" },
    { platform: "github", href: "https://github.com/yourorg", label: "GitHub" },
    { platform: "linkedin", href: "https://linkedin.com/company/yourbrand", label: "LinkedIn" },
  ],
},

platform is metadata for your own organization; rendering uses label and href. Add or remove entries freely — an empty array hides the social row.

Pricing page

/pricing/ renders plans fetched at build time (SSG). Cards are not hard-coded in the Astro template.

What gets included

Backend publicProducts with type: recurring returns recurring products where in_stock is null or greater than zero, sorted by position, with active prices included (publicPricing.ts). Each product includes:

name, prices[] (price in display dollars, currency, billing_period, is_default), top-level billing_period from the default price
description JSON (text + optional features)
trialable, is_default, seat/usage metadata derived from the default price

Marketing then:

Drops products with is_default: true (your free/default tier stays out of public pricing).
Maps description onto card fields (see table below).
Builds CTA links to signup → billing checkout for that product id.

Product description → card mapping

Store this JSON on the product description column (admin / editProduct):

{
  "text": "For agencies shipping and handing off multiple client product tracks.",
  "features": {
    "intro": "Complete Startup suite, plus:",
    "list": [
      { "title": "Up to 12 developer seats on GitHub & Discord" },
      { "title": "Access to a private Discord channel" },
      { "title": "Unlimited client handoffs" }
    ]
  }
}

Card region	Product field
Title	`name`
Price	Selected entry from `prices[]` (`mapGraphqlPlan` / period helpers; display dollars from `unit_amount`)
Description paragraph	`description.text`
“Features” intro line	`description.features.intro`
Bulleted features	`description.features.list[].title` (optional `subtitle`)
CTA	`/signup?redirect=/admin/settings/billing/checkout/<productId>`

Usage-based bands from the default price’s usage metadata append as extra feature lines automatically.

Billing period toggle

When pricing.billingToggle is true and a plan’s prices[] includes both monthly and yearly rows, PricingDisplay shows a Monthly / Yearly control and picks the matching price via billingPeriod. Cards carry data-billing-period and toggle visibility client-side.

Build-time fetch and fallback

Environment	Behavior
Production / CI	Must reach GraphQL; `onBuildFetchFailure: "fail"` aborts the build if fetch fails
Local dev	Tries GraphQL first; on failure uses `pricing.dev-snapshot.json` when `onBuildFetchFailure: "dev-snapshot"` or `MARKETING_PRICING_BUILD_FALLBACK=dev-snapshot`

GraphQL URL resolution (graphqlPricingProvider.ts):

When	Resolution
Build time (pricing SSG, Docker)	`MARKETING_GRAPHQL_URL` if set, else `http://MARKETING_BACKEND_HOST:MARKETING_BACKEND_PORT/graphql` (defaults `backend:3000` in Compose)
Production runtime (blog SSR, embedded in backend)	`applyMarketingSsrGraphqlEnv` sets `MARKETING_GRAPHQL_URL` from `marketing.graphqlUrl` (`http://127.0.0.1:$PORT/graphql`) unless a non-empty env override exists. Empty Docker build `ENV` (`""`) is treated as unset.
Local dev (marketing service on :4010)	Same as build-time defaults — `backend:3000` via Compose DNS; do not change `graphqlPricingProvider.ts` defaults for dev.

Currency for publicProducts (resolveMarketingPricingCurrency):

When	Resolution
Any	`MARKETING_PRICING_CURRENCY` if set, else `STRIPE_DEFAULT_CURRENCY` from `.env.development` / runtime (same as billing catalog), else `USD`

Marketing (and publicProducts) resolve one currency per request. Refract does not offer multi-currency subscription migrations; changing a live plan between currencies (for example EUR → USD) requires cancel + re-subscribe. See Billing — Single currency.

For local marketing builds without the API up, set MARKETING_PRICING_BUILD_FALLBACK=dev-snapshot or keep pricing.onBuildFetchFailure: "dev-snapshot" in config. Update apps/marketing/src/config/landing/pricing.dev-snapshot.json when you need representative cards offline.

Enterprise row

Below the grid, pricing.enterpriseCta renders a “Need a custom plan?” band linking to contact (or any LandingCta you configure).

Other pages

Route	Source
`/`	`pages/index.astro` + `HOME_SECTIONS`
`/pricing/`	`pages/pricing/index.astro` + `loadPlansForBuild`
`/contact/`	`pages/contact/index.astro` + `contact` config (`mailto` provider today)
`/legal/privacy/`, `/terms/`, `/licenses/`	Legal templates + `legal` config placeholders
`/robots.txt`, sitemap	Astro integrations + `siteUrl`

Legal pages validate required placeholders via validateLegalConfig — replace LEGAL_PLACEHOLDER_* values in landing.config.ts before production.

Local development

Marketing runs as the marketing service in Docker Compose. With make start, Caddy on port 8888 serves marketing routes on the unified origin (APP_URL). Marketing owns the root dev namespace (/@vite, /src, /_astro/*); portal dev assets live under /__portal/ (see Configuration). New pages under apps/marketing/src/pages/ need no Caddyfile.dev edit — the marketing catch-all handles them.

make start
# Open http://localhost:8888/ (home) and http://localhost:8888/pricing/

make build module=marketing
make lint module=marketing
make test module=marketing

GDPR consent, Google Analytics (consent-gated), and marketing event tracking are wired in GdprBody.astro and marketingAnalytics.ts. See GDPR consent flow and Frontend tracking.

Extending the marketing site

Brand copy — Edit apps/marketing/src/landing.config.ts (organization, navigation, SEO, social).
Homepage layout — Reorder or edit sections in apps/marketing/src/config/landing/sections/home.ts.
Theme — Swap or fork a preset in apps/marketing/src/config/landing/presets/.
Product cards — Update product description JSON in admin; set position and is_default on recurring products.
New section type — Add the TypeScript type, Astro component, and SectionRenderer case.
Verify — make build module=marketing and spot-check /, /pricing/, and Lighthouse SEO on home.

Example: add a new split section to the homepage.

// apps/marketing/src/config/landing/sections/home.ts
{
  type: "split",
  id: "split-analytics",
  layout: "image-right",
  headline: "Privacy-first analytics",
  body: "Consent-gated tracking with GA4 Consent Mode v2.",
  illustration: "icon",
  icon: "shield-check",
  cta: {
    label: "Read the docs",
    href: "/docs",
    ctaId: "split-analytics-cta",
    variant: "secondary",
  },
},

What not to do

❌ Never duplicate your product catalog in marketing config — pricing comes from publicProducts at build time.

❌ Never expose the default (is_default) product on /pricing/ — it is intentionally filtered out.

❌ Never ship with LEGAL_PLACEHOLDER_* or example social URLs still in landing.config.ts.

❌ Never hard-code checkout URLs without the signup redirect wrapper — use buildBillingCheckoutSignupHref() from apps/marketing/src/config/landing/appLinks.ts so post-auth routing works.

File conventions

Kind	Location
Site config	`apps/marketing/src/landing.config.ts`
Types / contracts	`apps/marketing/src/config/landing/types.ts`
Theme presets	`apps/marketing/src/config/landing/presets/`
Homepage sections	`apps/marketing/src/config/landing/sections/home.ts`
Section components	`apps/marketing/src/components/landing/`
Pricing UI	`apps/marketing/src/components/pricing/`
Public assets	`apps/marketing/public/`

What’s next?

Frontend overview — portal app, GraphQL hooks, and Apollo
Billing architecture — products, checkout, and subscriptions
GDPR consent flow — cookie banner and analytics gating
Frontend tracking — marketing CTA events and analytics
Configuration — environment variables including APP_URL
Cloudflare deployment — hosting the marketing build

Getting Started

Architecture

Frontend

Deployment

Quality

Reference

Marketing site & landing page

Marketing site & landing page

How it works

The config file

Theme

Homepage sections

SEO & discovery

Adding a static marketing page

Pricing page

What gets included

Product description → card mapping

Billing period toggle

Build-time fetch and fallback

Enterprise row

Other pages

Local development

Extending the marketing site

What not to do

File conventions

What’s next?

​Marketing site & landing page

​How it works

​The config file

​Theme

​Homepage sections

​SEO & discovery

​Adding a static marketing page

​Navigation, footer, and social links

​Pricing page

​What gets included

​Product description → card mapping

​Billing period toggle

​Build-time fetch and fallback

​Enterprise row

​Other pages

​Local development

​Extending the marketing site

​What not to do

​File conventions

​What’s next?

Marketing site & landing page

How it works

The config file

Theme

Homepage sections

SEO & discovery

Adding a static marketing page

Navigation, footer, and social links

Pricing page

What gets included

Product description → card mapping

Billing period toggle

Build-time fetch and fallback

Enterprise row

Other pages

Local development

Extending the marketing site

What not to do

File conventions

What’s next?