interactive-site-architecture

Interactive Site Architecture

Outcome

Create a production public-facing Next.js site whose content, narrative, visual identity, and interaction quality matter. This is a universal architecture for content-led sites: brand and marketing sites, SaaS and product sites, launch pages, editorial properties, portfolios, communities, conferences, documentation-shaped sites, and immersive showcases.

The core is fixed:

• server-rendered content;
• narrow client islands;
• validated content contracts;
• shared design and motion tokens;
• native browser behavior;
• SEO and accessibility in the server response;
• route-scoped performance budgets.

Select the modules the product needs:

Module	Use when
Content collection and detail	The site has projects, articles, products, people, events, or similar records
Portfolio or case studies	The organization needs proof through work
Immersive archive	Visual exploration is a primary product surface
Store	The site sells digital or physical products
CMS adapter	Editors publish independently of releases
Contact form	A mail link or calendar is insufficient

Do not force optional modules into a site that does not need them.

Typical profiles reuse the same core:

• SaaS or product: landing, offer, features, content collection, docs or changelog.
• Brand or launch: campaign narrative, product reveal, waitlist, social proof.
• Editorial: collection index, article detail, authors, topics, search.
• Community or conference: speakers, schedule, sessions, venue, tickets.
• Portfolio: project index, case detail, visual archive, contact.
• Commerce: catalog, product detail, checkout, download or fulfillment.

Read before acting

• Read references/architecture-contract.md for every build, redesign, or architecture change.
• Read references/code-architecture.md before creating folders, contracts, services, adapters, or server actions.
• Read references/dependency-matrix.md before installing, upgrading, or removing dependencies.
• For a new application, follow references/build-playbook.md.
• For new routes, content types, islands, archives, store products, or migrations, follow references/evolve-playbook.md.
• Before acceptance or release, follow references/quality-gates.md.

Reusable templates live under assets/templates/. Start from them only when they match the chosen architecture. Do not copy every template blindly.

Non-negotiable invariants

1. Keep page composition and primary content in Server Components by default.
2. Put use client at the smallest viable leaf. Animate server-rendered children through client wrappers when possible.
3. Treat TypeScript data contracts as the source of truth for every content entity, metadata record, gallery, and sitemap entry.
4. Give every overlay interaction a real route that works without client state, JavaScript, or a hash.
5. Use native HTML behavior first: links, buttons, forms, <dialog>, focus management, and browser history.
6. Keep secrets in server-only modules. Only public identifiers may use NEXT_PUBLIC_*.
7. When commerce exists, keep prices, entitlement decisions, payment confirmation, and protected downloads on the server.
8. Respect prefers-reduced-motion, keyboard navigation, visible focus, semantic headings, and no-script readability.
9. Keep content for one route out of another route's initial client bundle. Pass small summaries from the server when a client shell needs a count or label.
10. Use a modular monolith with thin route adapters, owned feature modules, explicit ports, and a single composition boundary.
11. Prefer stable dependencies. Do not start a new production app on a canary React build.

Default stack

Use the exact validated versions in the dependency matrix unless the site has a documented reason to differ.

• Node 26 LTS family and pnpm.
• Next.js App Router, React, React DOM, TypeScript.
• Tailwind CSS 4 for tokens, reset, and utility layout.
• CSS Modules for route or component-specific composition.
• Motion for React orchestration and gestures.
• Native dialog, Canvas, SVG, CSS, and Web Animations API for interactions where they are sufficient.
• Lucide icons imported individually.
• Zod for content and external input boundaries.
• Vercel for deployment, analytics, and image delivery.
• Stripe Embedded Checkout and server actions when commerce is required.

Working sequence

1. Inventory the public surfaces: landing pages, content indexes, detail routes, conversion paths, legal routes, search, archive, and commerce.
2. Freeze the route manifest and client boundary map before implementation.
3. Assign feature owners, ports, route adapters, and external adapters before creating files.
4. Model content entities and required media before building sections.
5. Establish global tokens, typography, spacing, states, reduced-motion behavior, and image conventions.
6. Build the server shell, navigation, route fallbacks, and SEO metadata.
7. Add client islands one at a time. Record why each must be client-side.
8. Build overlays with native dialog and URL state. Add the canonical page route at the same time.
9. Add complex visuals after their data, fallback, reduced-motion behavior, and performance bounds are defined.
10. Add CMS, commerce, accounts, or persistence only when the operating model requires them.
11. Run the architecture boundary check, structural audit, focused tests, quality gates, and production preview acceptance.
12. Report implemented behavior, verified evidence, and unverified limitations separately.

Decision rules

• Use CSS transitions for hover, focus, press, reveal, marquee, and simple state changes.
• Use Motion for coordinated variants, layout transitions, drag, presence, and scroll-linked orchestration.
• Use Canvas or WebGL only when the visual cannot be expressed reliably with DOM, SVG, and CSS. Add visibility pausing, DPR limits, cleanup, reduced-motion behavior, and a static fallback.
• Keep content collections server-rendered. Send only counts, labels, or selected records to a client overlay shell.
• Use a native <dialog> for previews and sheets when the same content also has a canonical page. Use a dedicated route for deep, long, or independently linked content.
• Use validated code content for a small team that releases with the app. Introduce a CMS behind a repository adapter when editors need independent publishing.
• Use a stateless Stripe session when the store only needs immediate purchase and download. Add a database and verified webhooks when the product needs entitlements, refunds, accounts, order history, or retries.
• Add Radix, shadcn, or another component library only after identifying the primitive it owns. Native elements and site-owned primitives are the baseline.
• Treat portfolios, archives, and stores as modules. They reuse the core content, route, style, motion, and security contracts.

Required build artifacts

Create and maintain these site-level artifacts:

• docs/architecture.md: route map, client boundaries, content ownership, external services, and performance budgets.
• src/features/*/domain and src/features/*/application: validated contracts and capabilities.
• src/platform/*: external adapters and the server-only composition root.
• src/shared/*: proven cross-feature contracts and design primitives.
• src/components/*: server composition and client islands with explicit names.
• src/app/*: pages, layouts, metadata, sitemap, robots, and route handlers.
• .env.example: names and purpose, never real secrets.
• Tests for content validation, client state machines, server actions, and critical browser journeys.
• A release checklist with preview, browser, accessibility, performance, SEO, and conditional commerce evidence.

Structural audit

Run the architecture boundary check and bundled audit after scaffolding and before release:

pnpm arch:check
node scripts/audit_site.mjs --root /path/to/app

Use --strict in CI when warnings should fail. The script checks dependency presence, route and content structure, client/server secret hazards, dialog and motion safeguards, tests, SEO files, and source-map exposure. It complements tests and does not replace them.

Completion contract

A build is complete only when:

• the route and boundary map matches the implementation;
• the dependency graph is acyclic and arch:check passes;
• routes use feature public APIs and the composition root owns wiring;
• the app builds without canary or peer-dependency surprises;
• critical content appears in server HTML;
• overlays, menus, and keyboard paths work and restore focus;
• reduced-motion and no-script fallbacks are verified;
• metadata, sitemap, robots, canonical URLs, and social images are present;
• initial route JS and image payloads stay within the documented budgets;
• commerce, when present, uses server-owned prices, server-side confirmation, and protected downloads;
• preview and production evidence are recorded separately.