pn-new-crm/04-ARCHITECTURE-COMPARISON.md

Port Nimara CRM — Full-Stack Architecture Comparison

Compiled: 2026-03-11 Context: AI-first development (Claude Code + Codex), self-hosted Docker, real-time updates required, PostgreSQL + Drizzle ORM already decided, website is separate codebase needing public API

---

Constraints (apply to ALL options)

These are fixed regardless of framework choice:

Constraint	Detail
Database	PostgreSQL + Drizzle ORM
Auth	Keycloak OIDC (existing infrastructure)
File storage	MinIO S3 (existing infrastructure)
E-signatures	Documenso (existing infrastructure, self-hosted)
Deployment	Docker containers, self-hosted server, Gitea CI/CD
Real-time	Live updates required (berth status changes, interest updates, signature events)
Public API	REST endpoints for website berth map + interest registration
Development	AI-assisted (Claude Code / Codex writing ~90%+ of code)
Team size	Solo developer (Matt) + AI tools

---

Option A: Next.js (React) + tRPC

The Stack

Layer	Technology
Framework	Next.js 15 (App Router)
Language	TypeScript (strict)
UI library	React 19
Styling	Tailwind CSS + Maritime design tokens
Components	shadcn/ui (copy-paste, Radix primitives, fully customizable)
Internal API	tRPC v11 (type-safe, no API routes to define for CRM pages)
Public API	Next.js Route Handlers (REST endpoints for website)
Real-time	tRPC subscriptions over WebSocket (via ws or uWebSocket)
State	TanStack Query (server state) + Zustand (UI state)
ORM	Drizzle ORM
Jobs	BullMQ + Redis
Containerization	Docker (node:20-alpine) + nginx reverse proxy

How it handles your CRM use cases

Interest CRUD: tRPC procedure interests.create / interests.update / interests.list — fully type-safe from database schema to UI component. Change a field in Drizzle schema, TypeScript immediately flags every component that references it.

Real-time berth status: tRPC subscription berths.onStatusChange — when a berth is linked to an interest and auto-moves to "Under Offer", all connected clients receive the update via WebSocket. No polling needed.

EOI/Documenso workflow: Server-side tRPC procedures handle the full lifecycle. Webhook endpoint is a standard Next.js Route Handler (REST, since Documenso calls it externally).

Public berth map API: Standard Next.js Route Handlers — GET /api/public/berths and POST /api/public/interests. These are separate from tRPC and serve the website.

Spec sheet import (AI-assisted): Upload endpoint receives PDF/Excel, server-side processing with SheetJS (Excel) or PDF extraction, AI API call to interpret/map columns, preview diff shown to admin, confirmation triggers bulk upsert via Drizzle.

Docker deployment: Official self-hosting guide. Standalone output mode produces a minimal Node.js server. Requires nginx reverse proxy for production (handles TLS, rate limiting, slow connections). Redis sidecar for BullMQ + session cache.

Assessment

Dimension	Rating	Notes
AI code generation quality	Excellent	Largest training corpus. Claude Code is most fluent with React/Next.js. shadcn/ui has massive example coverage.
Component ecosystem	Excellent	Deepest of any framework. Every library has a React-first version. TanStack Table, React Hook Form, Recharts, etc.
tRPC integration	Excellent	First-class support. Most tRPC examples are Next.js.
Real-time (WebSocket)	Good	Works but requires separate WebSocket server alongside Next.js (Vercel doesn't support WS, but irrelevant for self-hosting). Needs next-ws or custom server.
Self-hosted Docker	Good	Works well with standalone output mode. Requires nginx reverse proxy. More configuration than Nuxt/SvelteKit.
Bundle size / performance	Adequate	React runtime is larger than alternatives. For an internal CRM used by a small team, this is irrelevant.
Learning curve (reading code)	Moderate	JSX, hooks, useEffect patterns. React has more "gotchas" than Vue/Svelte but AI handles them well.
Long-term maintenance	Excellent	Backed by Vercel. Massive community. Won't disappear.

Pros:

• AI tools generate the most reliable code in this ecosystem
• Largest component library ecosystem by far
• tRPC + Drizzle + Next.js is an extremely well-documented combination
• shadcn/ui gives you beautiful, accessible components you fully own and can restyle to Maritime
• TanStack Query handles caching, optimistic updates, background refresh out of the box
• Most Stack Overflow answers, most GitHub examples, most blog posts

Cons:

• React's mental model (hooks, closures, re-renders) can be confusing when reading/debugging
• WebSocket support needs custom server setup (not complex, but not built-in)
• Next.js is optimized for Vercel — self-hosting works but you miss some platform features
• Heavier runtime than Svelte (irrelevant for small team internal tool)
• App Router patterns still evolving — some tutorials use old Pages Router

---

Option B: Nuxt 3 (Vue) + tRPC

The Stack

Layer	Technology
Framework	Nuxt 3 (latest)
Language	TypeScript (strict)
UI library	Vue 3 (Composition API)
Styling	Tailwind CSS + Maritime design tokens
Components	Nuxt UI v3 (Radix Vue based, Tailwind-native) OR Radix Vue + custom
Internal API	trpc-nuxt (community adapter)
Public API	Nitro server routes (REST endpoints for website)
Real-time	Nitro WebSocket (experimental) or Socket.io alongside Nitro
State	VueQuery / TanStack Query Vue (server state) + Pinia (UI state)
ORM	Drizzle ORM
Jobs	BullMQ + Redis
Containerization	Docker (node:20-alpine), Nitro handles both API + SPA

How it handles your CRM use cases

Interest CRUD: trpc-nuxt procedures with same type-safety pattern as Next.js. Vue's Composition API (ref, computed, watch) is arguably more intuitive than React hooks for someone reading code.

Real-time berth status: Nitro's experimental WebSocket support (CrossWasm v1 in Nitro v3). Less mature than the Next.js WebSocket ecosystem. Alternatively, run Socket.io alongside Nitro — works but adds complexity.

EOI/Documenso workflow: Nitro server routes handle webhooks. Same pattern as current system (Nitro is what you already have).

Public berth map API: Nitro server routes — cleaner than Next.js Route Handlers. Nitro is genuinely good at this.

Spec sheet import: Same approach as Next.js — server-side processing with AI interpretation.

Docker deployment: Nitro's output is a self-contained Node.js server. No reverse proxy strictly required (though recommended). Simpler Docker setup than Next.js.

Assessment

Dimension	Rating	Notes
AI code generation quality	Good	Well-represented in training data. Slightly fewer examples than React. Claude Code handles Vue/Nuxt competently.
Component ecosystem	Good	Nuxt UI v3 is excellent and built specifically for Nuxt. Fewer third-party options than React.
tRPC integration	Adequate	Community adapter (trpc-nuxt). Works but fewer examples, less battle-tested than Next.js tRPC.
Real-time (WebSocket)	Adequate	Nitro WebSocket is experimental. Works with adapter-node but less mature. Socket.io fallback is proven.
Self-hosted Docker	Excellent	Nitro produces clean standalone output. Simplest Docker setup of the three.
Bundle size / performance	Good	Smaller than React, larger than Svelte.
Learning curve (reading code)	Easy	Vue's template syntax is the most readable. <script setup> is clean. Closest to plain HTML.
Long-term maintenance	Good	Backed by Nuxt Labs. Strong community. Stable but smaller than React ecosystem.

Pros:

• You already have familiarity with the patterns from the current codebase
• Vue's template syntax is the most human-readable (easiest to understand when reviewing AI output)
• Nitro server is genuinely excellent for API routes and deployment flexibility
• Nuxt UI v3 is tightly integrated and well-maintained by the Nuxt team
• Simplest Docker deployment (Nitro just works)
• Pinia + VueQuery is a clean state management story

Cons:

• Smaller AI training corpus than React — more edge cases where Claude Code may hallucinate APIs
• tRPC support is community-maintained, not official
• WebSocket/real-time support is less mature than alternatives
• Fewer third-party component libraries to choose from
• Risk of repeating patterns from the current codebase rather than improving them

---

Option C: SvelteKit + tRPC

The Stack

Layer	Technology
Framework	SvelteKit 2
Language	TypeScript (strict)
UI library	Svelte 5 (runes)
Styling	Tailwind CSS + Maritime design tokens
Components	Skeleton UI or shadcn-svelte (Bits UI based)
Internal API	trpc-sveltekit (community adapter)
Public API	SvelteKit server routes (REST endpoints for website)
Real-time	trpc-sveltekit experimental WS or Socket.io sidecar
State	TanStack Query Svelte (server state) + Svelte stores (UI state)
ORM	Drizzle ORM
Jobs	BullMQ + Redis
Containerization	Docker (node:20-alpine) via adapter-node

How it handles your CRM use cases

Interest CRUD: trpc-sveltekit procedures. Svelte's reactivity model is the simplest of the three — $state rune replaces React's useState, Vue's ref. Less boilerplate.

Real-time berth status: Experimental WebSocket via trpc-sveltekit (only works with adapter-node). Less mature than both Next.js and Nuxt options.

EOI/Documenso workflow: SvelteKit server routes. Clean pattern but fewer examples specific to webhook handling.

Public berth map API: SvelteKit server routes. Works well, similar to Nuxt's Nitro routes.

Spec sheet import: Same approach as others. Fewer AI-processing library examples in Svelte ecosystem.

Docker deployment: adapter-node produces a clean, lightweight Node server. Smallest footprint of the three.

Assessment

Dimension	Rating	Notes
AI code generation quality	Adequate	Smallest training corpus. Svelte 5 runes are new — AI tools may generate Svelte 4 patterns. More manual correction needed.
Component ecosystem	Limited	Skeleton UI and shadcn-svelte exist but are less mature. Many libraries are React/Vue only.
tRPC integration	Adequate	Community adapter. WebSocket support explicitly marked "experimental".
Real-time (WebSocket)	Limited	SvelteKit doesn't natively support WebSockets. Experimental via adapter-node only. Most constrained option.
Self-hosted Docker	Excellent	Smallest container image. Lowest resource usage. Cleanest adapter-node output.
Bundle size / performance	Excellent	40-60% smaller bundles than React. Fastest runtime. Lowest memory usage.
Learning curve (reading code)	Easy	Most intuitive syntax. Closest to vanilla HTML/JS. Svelte 5 runes are clean.
Long-term maintenance	Good	Strong community, Vercel backing. Smaller ecosystem means fewer resources if you hit edge cases.

Pros:

• Smallest bundle size and lowest resource usage (best for self-hosting efficiency)
• Most intuitive syntax — easiest to read and understand as a non-programmer
• Svelte 5 runes are the cleanest reactivity model available
• Lightest Docker footprint
• Developer experience is genuinely the best of the three for humans

Cons:

• Smallest AI training corpus — Claude Code and Codex will produce less reliable code, especially for complex patterns
• Svelte 5 is recent — AI tools may mix up Svelte 4 and Svelte 5 syntax
• Weakest real-time/WebSocket story — experimental only
• Smallest component ecosystem — you'll build more from scratch
• Fewer Stack Overflow answers and GitHub examples to draw from when stuck
• Some React-only libraries have no Svelte equivalent (form builders, advanced table components, etc.)

---

Option D: Next.js (React) + REST (no tRPC)

Same as Option A but replacing tRPC with traditional REST API routes. Included because tRPC adds complexity and you may prefer a simpler architecture.

Differences from Option A

Aspect	tRPC (Option A)	REST (Option D)
API definition	Procedures on server, auto-typed on client	Route Handlers on server, manual fetch + types on client
Type safety	Automatic end-to-end	Manual (Zod schemas shared, but not enforced across boundary)
Code generation	Less code (no fetch wrappers needed)	More code (API client layer, type definitions)
Public API for website	Separate REST routes alongside tRPC	Same REST routes serve both CRM and website
Real-time	tRPC subscriptions (WebSocket)	Socket.io or Server-Sent Events (separate from API)
External consumers	tRPC only works with TypeScript clients	REST works with any client (mobile app, website, third-party)
Complexity	Higher (tRPC + REST coexist for different consumers)	Lower (one pattern for everything)
Debugging	tRPC calls don't show in browser Network tab as clean REST calls	Standard HTTP requests, easy to inspect

Assessment

Dimension	Rating	Notes
AI code generation quality	Excellent	Even more training data for REST patterns than tRPC.
Simplicity	Excellent	One pattern. No tRPC learning curve. Every endpoint is a standard HTTP route.
Type safety	Good	Zod validation + shared types. Not automatic like tRPC but works well.
Real-time	Good	Socket.io alongside Next.js is well-documented. Or Server-Sent Events for simpler cases.
External API consumers	Excellent	Same API serves CRM, website, and any future mobile app or integration.
OpenAPI compatibility	Excellent	REST routes can auto-generate OpenAPI docs. tRPC cannot.

Pros:

• Simplest mental model — everything is HTTP requests
• One API pattern instead of tRPC + REST coexisting
• Easier to debug (browser Network tab shows clean requests)
• Same API serves CRM and website (no separate public routes needed)
• If you ever build a mobile app or external integration, the API is ready
• More AI training examples for REST than tRPC

Cons:

• More boilerplate (API client layer, manual type sharing)
• No automatic type safety across client-server boundary
• Need to manually keep request/response types in sync
• Real-time requires a separate Socket.io or SSE layer

---

Head-to-Head Comparison

Factor	Next.js + tRPC (A)	Nuxt 3 + tRPC (B)	SvelteKit + tRPC (C)	Next.js + REST (D)
AI code gen reliability	★★★★★	★★★★	★★★	★★★★★
Component ecosystem	★★★★★	★★★★	★★★	★★★★★
Real-time maturity	★★★★	★★★	★★	★★★★
Docker self-hosting	★★★★	★★★★★	★★★★★	★★★★
Type safety (end-to-end)	★★★★★	★★★★	★★★★	★★★
Code readability	★★★	★★★★	★★★★★	★★★
Architecture simplicity	★★★	★★★	★★★	★★★★★
Bundle size / performance	★★★	★★★★	★★★★★	★★★
Public API flexibility	★★★	★★★★	★★★	★★★★★
Long-term ecosystem	★★★★★	★★★★	★★★★	★★★★★

---

Recommendation Matrix

If AI code generation reliability is your top priority → Option A or D (Next.js)

If deployment simplicity matters most → Option B (Nuxt) or C (SvelteKit)

If you want the simplest architecture to understand and maintain → Option D (Next.js + REST)

If you want maximum type safety with minimum code → Option A (Next.js + tRPC)

If performance and resource efficiency matter most → Option C (SvelteKit)

---

Author's Recommendation

Option D (Next.js + REST) is the strongest fit for your specific situation. Here's why:

1. AI-first development: Next.js React has the deepest training corpus. REST has even more examples than tRPC. You're optimizing for AI output quality, and this combination maximizes it.

2. Architectural simplicity: tRPC is elegant but adds a second API paradigm alongside the REST routes you need for the website anyway. With REST-only, every endpoint follows the same pattern — simpler for AI tools to generate consistently and simpler for you to understand.

3. Real-time: Socket.io alongside Next.js is battle-tested and well-documented. Simpler than tRPC subscriptions, which require a custom WebSocket server.

4. Public API: The same REST endpoints serve the CRM frontend, the website berth map, and any future integration. No separate public routes to maintain.

5. Future-proofing: If you ever need a mobile app, an external integration, or OpenAPI documentation, REST is ready. tRPC locks you into TypeScript clients.

6. Self-hosting: Next.js standalone output in Docker behind nginx is well-documented. Not the simplest (Nuxt wins there), but the trade-off for the ecosystem advantages is worth it.

The one thing you'd give up vs. Option A is automatic end-to-end type safety. But with Zod schemas shared between server and client plus TanStack Query's typed hooks, the gap is small in practice.

Runner-up: Option A (Next.js + tRPC) if you value automatic type safety highly and don't mind two API paradigms coexisting.