A Small Architecture Review Checklist for Growing Astro and Next Applications

Most reviews need a short list of decisions that are easy to revisit before they harden into accidental platform rules.

Architecture reviews are useful when they are small enough to happen before a feature hardens. For Astro and Next applications, the review does not need a ceremony. It needs a short pass over routes, rendering mode, data ownership, shared code, environment variables, and rollback.

The drift usually starts quietly: a marketing page imports dashboard utilities, a content collection starts carrying product state, or a server-only helper leaks into a client component.

Write a route decision table

Start with the routes touched by the change:

Route	Mode	Why	Risk
`/posts/[slug]/`	static	public content changes only on publish	future dates must be filtered
`/account/settings/`	server-rendered	depends on authenticated account	cache must be private
`/pricing/`	static + server checkout	copy is durable, checkout is dynamic	price verified server-side

This catches accidental complexity early. A page should not become dynamic because a shared layout imported a cookie helper.

Check data ownership

Astro content collections, MDX files, CMS fields, API responses, and database rows all have different owners. The review should ask:

Who edits this data?
Where is it validated?
How can it be previewed?
What happens when it is missing?
How does it reach search, RSS, sitemap, or caches?

For Next applications, also note cache lifetime and invalidation. Stale data is not always a bug, but the stale window should be intentional.

Treat shared folders with suspicion

A lib/ folder can become a junk drawer. Before moving code there, write down the runtime boundary:

lib/content/*: build-time and server-only content helpers
lib/server/*: server-only request and database helpers
lib/ui/*: runtime-safe UI primitives, no request data imports
lib/analytics/client.ts: browser-only analytics wrapper

Server-only helpers should be named or placed so they are hard to import into client components. UI primitives should not read cookies, headers, database clients, or CMS state.

List environment variables as part of the design

Environment variables shape architecture. A route that reads a private key cannot be static. A public feature flag needs a safe fallback. A preview build needs defaults that do not require production credentials.

Use a table in the PR:

Variable	Scope	Required	Read by	Build or runtime
`PUBLIC_SITE_URL`	public	yes	sitemap, canonical URLs	build
`CMS_TOKEN`	private	preview only	content preview API	runtime
`PUBLIC_ADSENSE_PUBLISHER_ID`	public	optional	ads metadata	build

This catches many failed deploys before they reach hosting.

Add an operational check

Before merge, the review should include a small verification record:

Checks:
- pnpm typecheck
- pnpm build
- opened changed route locally
- checked mobile viewport
- confirmed no draft route appears in sitemap
- rollback: revert PR and redeploy previous static build

The point is not to make every PR heavy. It is to ensure the next maintainer can understand the boundary without asking the original author.

Keep the decision note searchable

A short architecture note in the PR is enough:

Decision: keep article pages static.
Reason: public content changes through publishing workflow; no request-time identity needed.
Tradeoff: scheduled content appears only after a build.
Follow-up: add scheduled build trigger if editorial team needs exact publish time.

Small notes prevent accidental platform rules. The checklist should keep decisions visible, not create a new bureaucracy.