Skip to main content
reopt Handbook
reopt Handbook
Enterprise Project Architecture

Monorepo Foundation

Monorepo ArchitectureWorkspace DesignShared PackagesTurbo Pipeline

Apps and Delivery

Next.js PatternsVercel DeploymentCI/CD PipelineTesting Strategy

Agents and Operations

Agentic DevelopmentSkills EcosystemSecurity GovernanceMonitoring and Incident

Appendix

TemplatesReferencesUpdatesVerification
Handbook›Enterprise Project Architecture›Next.js Patterns
한국어KOEnglishEN

Next.js Patterns

Use App Router, server boundaries, data fetching, and route ownership consistently.

Written and reviewed by Eric Han · Co-founder & CTO, reopt

Key takeaways

  • Next.js architecture should make rendering, data access, and route ownership explicit to reduce accidental client complexity and route coupling.
  • Use the server side for secure data, secrets, session context, and bundle reduction; use the client only for interactivity, browser events, and browser-only APIs.
  • Keep data fetching close to route ownership, never pass secrets into client components, and make caching and revalidation visible in review.
  • In Next.js 16, prefer proxy.ts over middleware.ts (Node.js runtime, no runtime config), and enable cacheComponents with use cache, cacheLife, and cacheTag.
  • Keep slow data fetching out of Proxy, moving it to Route Handlers, Server Actions, or backend jobs, and use the codemod before large middleware renames.

Next.js architecture should make rendering, data access, and ownership explicit. Enterprise teams need conventions that reduce accidental client-side complexity and route-level coupling.

Route Ownership

AreaDecision
Route groupWhich product surface owns the route
LayoutShared navigation, auth, and data boundaries
PagePrimary user task and data dependency
Loading and errorExpected latency and failure state
MetadataSearch, sharing, and compliance needs

Server and Client Boundary

Use server-side whenUse client-side when
Fetching secure dataHandling interactive state
Reading secrets or session-only contextResponding to browser events
Rendering mostly static or request-scoped UIManaging rich controls or realtime updates
Reducing bundle sizeUsing browser-only APIs

Data Access Rules

  • Keep data fetching close to route or feature ownership.
  • Do not pass secrets or privileged data into client components.
  • Standardize error handling for expected failures.
  • Use shared API clients or schemas when multiple apps consume the same backend.
  • Make caching and revalidation choices visible in code review.

Next.js 16 Rules

AreaCurrent guidance
ProxyPrefer proxy.ts over middleware.ts; use it for lightweight routing, redirects, headers, and request-boundary logic
Proxy runtimeProxy uses the Node.js runtime in Next.js 16 and cannot be configured with runtime
CachingEnable cacheComponents and use use cache, cacheLife, and cacheTag for explicit cached pieces
Slow workKeep slow data fetching out of Proxy and move it to Route Handlers, Server Actions, or backend jobs
MigrationUse the Next.js codemod before renaming large middleware files manually

Review Checklist

  • Is the client boundary justified?
  • Can the route fail gracefully?
  • Is metadata complete for important public pages?
  • Are loading states stable on slow networks?
  • Does the route import only allowed package layers?
  • Are Proxy and caching decisions aligned with Next.js 16 behavior?

Related docs

Workspace Design

Define a repository layout and naming system that stays understandable as the project grows.

Access Control and Secrets

AI Security and Compliance Operations · Govern human, service, and agent permissions with least privilege and rotation.

MCP Integration

Claude Code Complete Guide · Connect Claude Code to tools and resources through Model Context Protocol servers.

Ch9. Channels, Auth, Streaming

Enterprise Eve Agent Development · How Eve channels own session creation, continuation tokens, route auth, NDJSON streams, and frontend/client integration.

Ch8. Sandbox Secure Runtime

Enterprise Eve Agent Development · Turn Eve sandbox trust boundaries, backends, network policy, credential brokering, and workspace lifecycle into operating standards.

Turbo Pipeline

Configure Turborepo tasks, caching, dependencies, and environment rules for enterprise delivery.

Vercel Deployment

Organize project, environment, preview, and production deployment rules for enterprise teams.

On this page

Route OwnershipServer and Client BoundaryData Access RulesNext.js 16 RulesReview Checklist