Architecture Decisions

Step 1: Understand rendering strategies

Before writing any code, you need to make an architecture decision that will shape everything else. Different pages on this site need different approaches to how they're built and delivered.

Static Site Generation (SSG) means the page is built once at deploy time. The HTML is ready before anyone visits. A CDN serves it from a server close to the visitor. Result: the fastest possible page load, because there's nothing to compute -- the page already exists.

The About page, the Visit page, the History page -- these don't change based on who's visiting or what they search for. They're the same for every tourist, every researcher, every member. Build them once and serve them instantly.

Server-Side Rendering (SSR) means the page is built fresh on each request. The server receives a request, fetches the relevant data, renders the HTML, and sends it. Result: the content is always current, but the server has to do work for every visitor.

The collection browsing page needs SSR. When a researcher searches for "18th century compass," the results depend on their query. The page can't be pre-built because the server doesn't know what someone will search for until they search.

Client-Side Rendering (CSR) means the server sends a minimal HTML shell, and JavaScript in the browser builds the page. Result: the page is interactive from the start, but the initial load is slower because the browser has to download and execute JavaScript before anything appears.

The members dashboard -- behind a login, interactive, showing personalized content -- fits CSR. It's only accessible to authenticated members, and the content changes based on who's logged in.

Step 2: Map your routes to strategies

Open materials/collection-data.json. This is the collection dataset -- 150 artifacts exported from the museum's legacy Access database. Browse through it. Each artifact has a category, an era, a description, and an image reference.

Now map the museum website's pages to rendering strategies:

Each choice has consequences. SSG pages are fast but can't show dynamic content. SSR pages are current but add server processing time. CSR pages are interactive but have slower initial loads. For Ivan's tourists on 3G in Dubrovnik's old town, the About page loading in under 100ms (SSG) versus 500ms (SSR) is the difference between someone deciding to visit and someone walking away.

Step 3: Plan Suspense boundaries

The collection page needs special attention. When a researcher opens it, the navigation and search bar should appear instantly. The search results can stream in -- the page is usable before all results have loaded.

Suspense boundaries control this. They tell Next.js: "show everything outside this boundary immediately, and show a loading state inside the boundary until the data arrives." Place them wrong and the user sees either a blank page (everything inside one boundary) or a jarring cascade of content appearing in waves (too many boundaries).

For the museum collection: the page shell (header, navigation, search bar, category filters) loads immediately. The artifact grid streams in. The artifact detail view (when someone clicks an item) streams in separately. Two boundaries, two loading states.

flowchart TD
    A[Museum Website] --> B[SSG Pages]
    A --> C[SSR Pages]
    A --> D[CSR Pages]
    B --> B1["/about"]
    B --> B2["/visit"]
    B --> B3["/history"]
    C --> C1["/collection - search/filter"]
    C --> C2["/collection/[id] - detail"]
    D --> D1["/members/dashboard"]
    D --> D2["/members/lectures"]
    D --> D3["/members/archives"]

Step 4: Write the CLAUDE.md governance file

This is the first project where you create the project governance file yourself. In previous projects, it was provided as a material. Now the architecture decisions are yours, and the governance file reflects them.

Create a CLAUDE.md in your project root. It should include:

• The project name, client, and what you're building
• The tech stack
• The rendering strategy decisions (which routes use which strategy and why)
• The ticket breakdown for the work ahead
• Verification targets (Lighthouse accessibility, keyboard navigation, server-side auth, custom metrics)
• The commit convention

The exemplar in materials/CLAUDE.md shows the structure. Your version should reflect the specific decisions you've made about rendering strategy, the constraints you discovered from Ivan, and the approach you're taking.

Step 5: Generate and review the project plan

Use plan mode to decompose the project. Ask Claude to propose a plan based on the architecture decisions in your CLAUDE.md. Review what it suggests:

• Does the plan build the schema before the API routes? (The API depends on the data model.)
• Does it implement auth before the members area? (Protected routes need auth to exist.)
• Does it put accessibility work after the basic build? (Accessibility should be integrated, not bolted on.)

AI generates plans based on common patterns, not on this project's specific dependencies. Adjust the plan where the sequencing doesn't match what you know about the project.