Architecture

Versioned infrastructure in core packages, owned visual code in the site, data files the CLI rewrites, generated files nobody edits.

Core and site

core/ (the framework)          site (the client project)
  packages/  @dss/*              site.manifest.ts   pages, modules, deploy, SEO, CSP, redirects
  registry/  sections, scenes    design.dna.ts      the Design DNA
  modules/   forms, blog...      content/*.ts       every visible word, typed
  template/  base site, presets  app/               thin pages: metadata + sections
  _ai/       AI layer            components/        owned sections, site chrome, 3D scenes
  cli/       dss                 server/            database and server actions

The core is attached as a git submodule pinned to a commit or tag (--copy makes a snapshot for client handoff, --link symlinks a framework checkout for development). Claude never edits core/ from a site (permission deny).

Packages

Package	Role
@dss/site	defineManifest (zod) and withDss: headers, CSP, images, redirects, deploy output
@dss/design	Design DNA, archetypes, font pairs, OKLCH palettes, theme generators
@dss/ui	token-driven primitives (Section, Heading, Media, ButtonLink, Accordion…)
@dss/seo	metadata, canonical, hreflang, JSON-LD, robots, sitemap, llms.txt, noindex on previews
@dss/security	static CSP and presets, safeAction, Turnstile, rate limiting, env validation
@dss/motion	CSS scroll-driven motion, marquee, split words, count-up
@dss/three	lazy three.js <Scene> with poster fallback
@dss/data	Drizzle on D1, libSQL or Postgres
@dss/aimkit	vendored AimKit bridge, MCP server and Chrome extension

Packages are TypeScript sources. Config-time imports (next.config.ts, site.manifest.ts, the CLI) go through Node-safe entries loaded with Node’s type stripping.

Ownership rules

• Generated, never edited: app/theme.css, app/fonts.ts, app/theme.ts, content/meta.ts, lib/modules.ts, components/site/module-slots.tsx, core/CATALOG.md, _ai/digest.md.
• Data files rewritten by the CLI: site.manifest.ts, design.dna.ts (keep literal values).
• Owned by the site: sections copied from the registry (each keeps a // dss-section: stamp and a @catalog line), module files, everything in content/.
• AI files: dss-* entries in .claude/ are overwritten by the sync; site-specific ones use site-.