ADR-002: ADR 002: Frontend Framework Selection - Remix over Next.js

Status: Proposed
Version: 1.0
Date: 2025-12-25
Supersedes: N/A
Related ADRs: N/A
Related PRDs: N/A

Context

The SEA-Forge™ platform requires a modern frontend framework to deliver interactive, real-time documentation, artifact generation, and architecture visualization capabilities. The primary candidates evaluated were Remix and Next.js, both React-based meta-frameworks with strong ecosystem support.

Decision

We adopt Remix as the frontend framework for SEA-Forge™.

Choose Remix because SEA-Forge™ is:

✅ A data-heavy application (not a marketing site)
✅ Server-side intensive (graph queries, validations, generations)
✅ Deeply nested information architecture
✅ Developer-focused (fast, clean URLs, no hydration mismatches)
✅ Self-hosted (not leveraging Vercel-specific features)

Remix’s philosophy of “use the platform” (web standards, HTTP, URLs) aligns perfectly with SEA-Forge™’s goal of being a transparent, understandable “living map” of enterprise architecture.

• ADR-001: Core Principles - Establishes “Code Is a Projection” principle
• ANALYSIS-001: SEA™ Original Domain Analysis - Documents frontend requirements
• VISION-001: SEA-Forge™ Master Vision - Defines platform goals

Rationale

TBD

Constraints

TBD

Quality Attributes

• First Contentful Paint: < 1.5s
• Time to Interactive: < 3s
• Largest Contentful Paint: < 2.5s
• Client Bundle Size: < 200KB (gzipped)

Bounded Contexts Impacted

TBD

Consequences

TBD

Additional Notes

Accepted

SEA-Forge™’s frontend must support:

1. Data-Intensive, Real-Time Operations

   • Live documentation that updates as code changes
   • Real-time artifact generation (maps, checklists, diagrams)
   • Continuous validation and compliance checking
   • Graph-based knowledge that’s constantly evolving

2. Complex, Nested Information Architecture

   • Multi-level documentation (project → service → API → components)
   • Hierarchical semantic definitions (domains → concepts → terms → rules)
   • Nested artifacts (timelines within checklists, diagrams within plans)
   • Interconnected knowledge graph views

3. Developer-Focused Experience

   • “Freedom from manual docs” promise
   • “Faster starting pace for new engineers”
   • Interactive exploration of architecture
   • Shareable deep links to specific rules, artifacts, validation results

4. Microservices Backend Integration

   • Kong API Gateway
   • Multiple backend services
   • Oxigraph graph queries (potentially expensive)
   • PostgreSQL relational data

5. Artifact Generation & Export

   • Documentation files (README, API specs)
   • Diagrams (architecture visualizations)
   • Checklists, maps, plans
   • Potentially large exports (PDFs, images, JSON)

6. Future Collaboration Features (Roadmap)

   • Real-time artifact collaboration
   • Multi-language support
   • Mobile interfaces

Remix Advantage:

• Remix’s loader/action pattern and built-in data revalidation makes it exceptionally good at keeping the UI synchronized with rapidly changing backend data
• Nested routing with parallel data loading means when an architecture changes, only affected sections re-fetch—not the entire page
• Server-first philosophy aligns with SEA-Forge™’s backend-heavy workload

Next.js Limitation:

• App Router adds complexity with multiple rendering strategies (ISR, ISG, SSR, CSR)
• Client-first bias pushes toward heavier client bundles
• Data revalidation requires more manual coordination

Remix Advantage:

• Nested routes designed for hierarchical data
• Each route segment loads its own data independently
• When navigating from projects/payment/architecture to projects/payment/validation, shared layouts don’t re-render and common data doesn’t refetch
• URL-driven state makes every view shareable and bookmarkable

Next.js Limitation:

• Nested layout data fetching still more cumbersome than Remix’s parallel route loaders
• More boilerplate for achieving the same result

Remix Advantage:

• Progressive enhancement: Works without JavaScript, critical for documentation accessibility
• URL-driven state: Perfect for shareable deep links to specific rules, artifacts, or validation results
• No client-side routing complexity: Server-rendered by default, faster perceived performance
• Simpler mental model: Web platform standards (HTTP, URLs, Forms)

Next.js Limitation:

• More “magic” abstractions that obscure the platform
• Hydration mismatches more common
• Steeper learning curve for junior developers

Remix Advantage:

• Loaders run on the server, so you can talk directly to databases/services without exposing APIs
• Built-in error boundaries per route segment (critical when different microservices might fail independently)
• Streaming SSR for handling slow Oxigraph graph queries without blocking the entire page
• Direct access to Oxigraph, PostgreSQL, Kong without extra API layers

Next.js Limitation:

• More likely to need tRPC or similar wrapper for type-safe server communication
• Error handling across nested layouts less elegant

Remix Advantage:

• Resource routes make it trivial to serve generated PDFs, images, JSON exports
• Actions can handle complex form submissions for artifact generation with proper error handling and optimistic UI
• File streaming built-in for large exports

Next.js Limitation:

• API routes adequate but less integrated with the routing system
• More manual plumbing required

Remix Advantage:

• Works well with WebSocket libraries for real-time features
• Progressive enhancement means mobile web works better on slower connections
• i18n is easier with server-side rendering
• Can integrate Partykit, Liveblocks, or similar collaboration tools cleanly

Next.js Limitation:

• More client-side focused, which works against collaboration performance

Remix Advantage:

• Deployment agnostic: Works on any Node.js server, Docker, serverless
• No vendor lock-in: Not tied to Vercel’s edge network
• Control over caching, rendering strategies without fighting framework defaults

Next.js Limitation:

• Optimized for Vercel deployment
• Self-hosting loses many of the “advanced” features (edge runtime, ISR)
• More complex to optimize outside Vercel ecosystem

✅ Faster initial page loads through aggressive server rendering
✅ Simpler data management with loaders/actions vs. multiple fetching patterns
✅ Better handling of microservices architecture via server-side data fetching
✅ Cleaner code for complex hierarchical views
✅ Progressive enhancement by default improves accessibility
✅ Smaller client bundles reduce JavaScript overhead
✅ Easier debugging with less client/server state mismatch

⚠️ Smaller ecosystem compared to Next.js (fewer tutorials, plugins)
⚠️ Less “magic” means more manual optimization in some cases
⚠️ Newer technology with less production battle-testing

• Ecosystem Gap: Leverage Remix’s compatibility with standard React libraries
• Manual Optimization: Document patterns in the codebase for consistency
• Production Risk: Gradual rollout, comprehensive testing, monitoring

Pros:

• Larger ecosystem and community
• Vercel’s edge network (if we moved to cloud)
• React Server Components for fine-grained component-level data fetching

Cons:

• Over-engineering risk: ISR, ISG, multiple rendering strategies add complexity SEA-Forge™ doesn’t need
• Client-side focus doesn’t align with our server-intensive workload
• Nested layout data fetching more cumbersome
• Optimized for marketing sites and e-commerce, not developer tools

Pros:

• Performance advantages over React
• Modern reactivity model

Cons:

• Too experimental for production
• Smaller ecosystem
• Team unfamiliarity with Solid.js

Pros:

• Excellent DX
• Smaller bundle sizes

Cons:

• Team unfamiliarity with Svelte
• Less mature ecosystem for enterprise features

1
2
3
4
5
6
7
8
9
web-app/
├── app/
│   ├── routes/          # File-based routing
│   ├── components/      # Shared React components
│   ├── services/        # Backend integrations (Oxigraph, PostgreSQL)
│   ├── utils/           # Shared utilities
│   └── root.tsx         # Root layout
├── public/              # Static assets
└── remix.config.js      # Remix configuration

• Oxigraph: Direct connection via loaders (server-side only)
• PostgreSQL: Prisma/Drizzle ORM in loaders
• Kong Gateway: Proxy through Remix routes with error boundaries
• Artifact Generation: Resource routes for downloads

2026-Q1 - Reassess after 6 months of production use

• Remix Documentation
• Remix vs Next.js Comparison (2024)
• Original SEA™ Frontend Analysis (conversation transcript)