# darkroomengineering/satus architecture

> Architecture diagram of the GitHub repository darkroomengineering/satus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darkroomengineering/satus
- Repository: https://github.com/darkroomengineering/satus

## Overview

Satūs is a Next.js starter for content-driven marketing and creative sites. Its main user path is the site landing page and routed content, rendered inside a shared experience wrapper; Sanity can supply CMS pages and articles, while SEO and agent-facing routes expose site content to crawlers and LLMs. Optional branches provide Shopify commerce, form-provider integrations, motion, and WebGL. The sampled sources show the wrapper, feature loading, route handling, and webhook dispatch; other documented capabilities are included without asserting unsampled call paths.

Main entry points: [`lib/integrations/shopify/client.ts`](https://github.com/darkroomengineering/satus/blob/main/lib/integrations/shopify/client.ts) (Shopify storefront), [`lib/features/index.tsx`](https://github.com/darkroomengineering/satus/blob/main/lib/features/index.tsx) (Optional feature loader), [`lib/seo/routes.ts`](https://github.com/darkroomengineering/satus/blob/main/lib/seo/routes.ts) (CMS route catalog), [`components/layout/wrapper/index.tsx`](https://github.com/darkroomengineering/satus/blob/main/components/layout/wrapper/index.tsx) (Page wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Site experience"]
  node_site_home["Manual homepage<br/>[page.tsx]"]
  node_site_routes["Content routes<br/>[page.tsx]"]
  node_article_route["Article pages<br/>[page.tsx]"]
  node_site_wrapper["Page wrapper<br/>[index.tsx]"]
end

subgraph group_content["Content and discovery"]
  node_sanity_studio["Sanity Studio<br/>[studio.tsx]"]
  node_sanity_client["Sanity client<br/>[client.ts]"]
  node_seo_routes["CMS route catalog<br/>[routes.ts]"]
  node_markdown_route["Markdown content endpoint<br/>[route.ts]"]
  node_llms_route["LLM site summary<br/>[route.ts]"]
  node_seo_helpers["SEO and metadata<br/>[site.ts]"]
  node_sitemap["Sitemap<br/>[sitemap.ts]"]
end

subgraph group_integrations["Optional integrations"]
  node_shopify["Shopify storefront<br/>[client.ts]"]
  node_cart_api["Cart ensure endpoint<br/>[route.ts]"]
  node_webhook_route["Revalidation dispatch<br/>[route.ts]"]
  node_sanity_revalidate["Sanity revalidation<br/>[revalidate.ts]"]
  node_shopify_revalidate["Shopify revalidation<br/>[revalidate.ts]"]
  node_provider_registry["Integration registry<br/>[registry.ts]"]
  node_mailchimp["Mailchimp client"]
end

subgraph group_runtime["Interactive runtime"]
  node_feature_loader["Optional feature loader<br/>[index.tsx]"]
  node_gsap_runtime["GSAP runtime<br/>[gsap.tsx]"]
  node_webgl_canvas["WebGL canvas<br/>[index.tsx]"]
  node_dev_tools["Development tools<br/>[index.tsx]"]
end

subgraph group_shared["Shared services"]
  node_environment["Validated environment<br/>[env.ts]"]
  node_rate_limit["Rate limiting<br/>[rate-limit.ts]"]
end

node_visitor(("Site visitor"))
node_cms_service[("Sanity CMS")]
node_shopify_service[("Shopify API")]
node_mailchimp_service[("Mailchimp API")]

node_visitor -->|"opens manual"| node_site_home
node_site_home -->|"renders in"| node_site_wrapper
node_site_routes -->|"renders in"| node_site_wrapper
node_article_route -->|"renders in"| node_site_wrapper
node_site_wrapper -.->|"mounts runtime"| node_feature_loader
node_sanity_studio -.->|"uses CMS"| node_sanity_client
node_seo_routes -->|"fetches content"| node_sanity_client
node_seo_routes -->|"queries routes"| node_cms_service
node_article_route -.->|"loads articles"| node_cms_service
node_markdown_route -->|"builds document"| node_seo_helpers
node_llms_route -->|"gets CMS routes"| node_seo_routes
node_llms_route -->|"uses site details"| node_seo_helpers
node_sitemap -.->|"lists CMS routes"| node_seo_routes
node_shopify -->|"requests storefront"| node_shopify_service
node_cart_api -.->|"ensures cart"| node_shopify
node_webhook_route -->|"limits requests"| node_rate_limit
node_webhook_route -->|"dispatches Shopify"| node_shopify_revalidate
node_webhook_route -->|"dispatches Sanity"| node_sanity_revalidate
node_sanity_revalidate -.->|"revalidates content"| node_cms_service
node_shopify_revalidate -.->|"handles webhook"| node_shopify_service
node_shopify -->|"checks setup"| node_provider_registry
node_mailchimp -->|"checks setup"| node_provider_registry
node_mailchimp -->|"submits contacts"| node_mailchimp_service
node_shopify -->|"reads configuration"| node_environment
node_mailchimp -->|"reads configuration"| node_environment
node_feature_loader -->|"loads optionally"| node_gsap_runtime
node_feature_loader -->|"loads canvas"| node_webgl_canvas
node_feature_loader -->|"loads in development"| node_dev_tools

click node_site_home "https://github.com/darkroomengineering/satus/blob/main/app/(site)/page.tsx"
click node_site_routes "https://github.com/darkroomengineering/satus/blob/main/app/(site)/%5B...slug%5D/page.tsx"
click node_article_route "https://github.com/darkroomengineering/satus/blob/main/app/(site)/articles/%5Bslug%5D/page.tsx"
click node_site_wrapper "https://github.com/darkroomengineering/satus/blob/main/components/layout/wrapper/index.tsx"
click node_sanity_studio "https://github.com/darkroomengineering/satus/blob/main/app/studio/%5B%5B...tool%5D%5D/studio.tsx"
click node_sanity_client "https://github.com/darkroomengineering/satus/blob/main/lib/integrations/sanity/client.ts"
click node_seo_routes "https://github.com/darkroomengineering/satus/blob/main/lib/seo/routes.ts"
click node_markdown_route "https://github.com/darkroomengineering/satus/blob/main/app/agent-content/route.ts"
click node_llms_route "https://github.com/darkroomengineering/satus/blob/main/app/llms.txt/route.ts"
click node_seo_helpers "https://github.com/darkroomengineering/satus/blob/main/lib/seo/site.ts"
click node_sitemap "https://github.com/darkroomengineering/satus/blob/main/app/sitemap.ts"
click node_shopify "https://github.com/darkroomengineering/satus/blob/main/lib/integrations/shopify/client.ts"
click node_cart_api "https://github.com/darkroomengineering/satus/blob/main/app/api/cart/ensure/route.ts"
click node_webhook_route "https://github.com/darkroomengineering/satus/blob/main/app/api/revalidate/route.ts"
click node_sanity_revalidate "https://github.com/darkroomengineering/satus/blob/main/lib/integrations/sanity/revalidate.ts"
click node_shopify_revalidate "https://github.com/darkroomengineering/satus/blob/main/lib/integrations/shopify/revalidate.ts"
click node_provider_registry "https://github.com/darkroomengineering/satus/blob/main/lib/integrations/registry.ts"
click node_mailchimp "https://github.com/darkroomengineering/satus/blob/main/lib/integrations/mailchimp/mailchimp-client.ts"
click node_feature_loader "https://github.com/darkroomengineering/satus/blob/main/lib/features/index.tsx"
click node_gsap_runtime "https://github.com/darkroomengineering/satus/blob/main/components/effects/gsap.tsx"
click node_webgl_canvas "https://github.com/darkroomengineering/satus/blob/main/lib/webgl/components/canvas/index.tsx"
click node_dev_tools "https://github.com/darkroomengineering/satus/blob/main/lib/dev/index.tsx"
click node_environment "https://github.com/darkroomengineering/satus/blob/main/lib/env.ts"
click node_rate_limit "https://github.com/darkroomengineering/satus/blob/main/lib/utils/rate-limit.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_site_home,node_site_routes,node_article_route,node_site_wrapper toneBlue
class node_sanity_studio,node_sanity_client,node_seo_routes,node_markdown_route,node_llms_route,node_seo_helpers,node_sitemap,node_cms_service,node_shopify_service,node_mailchimp_service toneAmber
class node_shopify,node_cart_api,node_webhook_route,node_sanity_revalidate,node_shopify_revalidate,node_provider_registry,node_mailchimp toneMint
class node_feature_loader,node_gsap_runtime,node_webgl_canvas,node_dev_tools toneRose
class node_environment,node_rate_limit,node_visitor toneIndigo
```

## Components

### Site experience

- [Manual homepage](https://github.com/darkroomengineering/satus/blob/main/app/(site)/page.tsx): `app/(site)/page.tsx`
- [Content routes](https://github.com/darkroomengineering/satus/blob/main/app/(site)/%5B...slug%5D/page.tsx): `app/(site)/[...slug]/page.tsx`
- [Article pages](https://github.com/darkroomengineering/satus/blob/main/app/(site)/articles/%5Bslug%5D/page.tsx): `app/(site)/articles/[slug]/page.tsx`
- [Page wrapper](https://github.com/darkroomengineering/satus/blob/main/components/layout/wrapper/index.tsx): `components/layout/wrapper/index.tsx`

### Content and discovery

- [Sanity Studio](https://github.com/darkroomengineering/satus/blob/main/app/studio/%5B%5B...tool%5D%5D/studio.tsx): `app/studio/[[...tool]]/studio.tsx`
- [Sanity client](https://github.com/darkroomengineering/satus/blob/main/lib/integrations/sanity/client.ts): `lib/integrations/sanity/client.ts`
- [CMS route catalog](https://github.com/darkroomengineering/satus/blob/main/lib/seo/routes.ts): `lib/seo/routes.ts`
- [Markdown content endpoint](https://github.com/darkroomengineering/satus/blob/main/app/agent-content/route.ts): `app/agent-content/route.ts`
- [LLM site summary](https://github.com/darkroomengineering/satus/blob/main/app/llms.txt/route.ts): `app/llms.txt/route.ts`
- [SEO and metadata](https://github.com/darkroomengineering/satus/blob/main/lib/seo/site.ts): `lib/seo/site.ts`
- [Sitemap](https://github.com/darkroomengineering/satus/blob/main/app/sitemap.ts): `app/sitemap.ts`

### Optional integrations

- [Shopify storefront](https://github.com/darkroomengineering/satus/blob/main/lib/integrations/shopify/client.ts): `lib/integrations/shopify/client.ts`
- [Cart ensure endpoint](https://github.com/darkroomengineering/satus/blob/main/app/api/cart/ensure/route.ts): `app/api/cart/ensure/route.ts`
- [Revalidation dispatch](https://github.com/darkroomengineering/satus/blob/main/app/api/revalidate/route.ts): `app/api/revalidate/route.ts`
- [Sanity revalidation](https://github.com/darkroomengineering/satus/blob/main/lib/integrations/sanity/revalidate.ts): `lib/integrations/sanity/revalidate.ts`
- [Shopify revalidation](https://github.com/darkroomengineering/satus/blob/main/lib/integrations/shopify/revalidate.ts): `lib/integrations/shopify/revalidate.ts`
- [Integration registry](https://github.com/darkroomengineering/satus/blob/main/lib/integrations/registry.ts): `lib/integrations/registry.ts`
- [Mailchimp client](https://github.com/darkroomengineering/satus/blob/main/lib/integrations/mailchimp/mailchimp-client.ts): `lib/integrations/mailchimp/mailchimp-client.ts`

### Interactive runtime

- [Optional feature loader](https://github.com/darkroomengineering/satus/blob/main/lib/features/index.tsx): `lib/features/index.tsx`
- [GSAP runtime](https://github.com/darkroomengineering/satus/blob/main/components/effects/gsap.tsx): `components/effects/gsap.tsx`
- [WebGL canvas](https://github.com/darkroomengineering/satus/blob/main/lib/webgl/components/canvas/index.tsx): `lib/webgl/components/canvas/index.tsx`
- [Development tools](https://github.com/darkroomengineering/satus/blob/main/lib/dev/index.tsx): `lib/dev/index.tsx`

### Shared services

- [Validated environment](https://github.com/darkroomengineering/satus/blob/main/lib/env.ts): `lib/env.ts`
- [Rate limiting](https://github.com/darkroomengineering/satus/blob/main/lib/utils/rate-limit.ts): `lib/utils/rate-limit.ts`

### Other components

- **Site visitor**
- **Sanity CMS**
- **Shopify API**
- **Mailchimp API**

## Connections

- Site visitor → Manual homepage: opens manual (evidence: `README.md`)
- Manual homepage → Page wrapper: renders in (evidence: `app/(site)/page.tsx`)
- Content routes → Page wrapper: renders in (evidence: `app/(site)/[...slug]/page.tsx`)
- Article pages → Page wrapper: renders in (evidence: `app/(site)/articles/[slug]/page.tsx`)
- Page wrapper → Optional feature loader: mounts runtime
- Sanity Studio → Sanity client: uses CMS
- CMS route catalog → Sanity client: fetches content (evidence: `lib/seo/routes.ts`)
- CMS route catalog → Sanity CMS: queries routes (evidence: `lib/seo/routes.ts`)
- Article pages → Sanity CMS: loads articles
- Markdown content endpoint → SEO and metadata: builds document (evidence: `app/agent-content/route.ts`)
- LLM site summary → CMS route catalog: gets CMS routes (evidence: `app/llms.txt/route.ts`)
- LLM site summary → SEO and metadata: uses site details (evidence: `app/llms.txt/route.ts`)
- Sitemap → CMS route catalog: lists CMS routes (evidence: `README.md`)
- Shopify storefront → Shopify API: requests storefront (evidence: `lib/integrations/shopify/client.ts`)
- Cart ensure endpoint → Shopify storefront: ensures cart
- Revalidation dispatch → Rate limiting: limits requests (evidence: `app/api/revalidate/route.ts`)
- Revalidation dispatch → Shopify revalidation: dispatches Shopify (evidence: `app/api/revalidate/route.ts`)
- Revalidation dispatch → Sanity revalidation: dispatches Sanity (evidence: `app/api/revalidate/route.ts`)
- Sanity revalidation → Sanity CMS: revalidates content
- Shopify revalidation → Shopify API: handles webhook
- Shopify storefront → Integration registry: checks setup (evidence: `lib/integrations/shopify/client.ts`)
- Mailchimp client → Integration registry: checks setup (evidence: `lib/integrations/mailchimp/mailchimp-client.ts`)
- Mailchimp client → Mailchimp API: submits contacts (evidence: `lib/integrations/mailchimp/mailchimp-client.ts`)
- Shopify storefront → Validated environment: reads configuration (evidence: `lib/integrations/shopify/client.ts`)
- Mailchimp client → Validated environment: reads configuration (evidence: `lib/integrations/mailchimp/mailchimp-client.ts`)
- Optional feature loader → GSAP runtime: loads optionally (evidence: `lib/features/index.tsx`)
- Optional feature loader → WebGL canvas: loads canvas (evidence: `lib/features/index.tsx`)
- Optional feature loader → Development tools: loads in development (evidence: `lib/features/index.tsx`)
