Overview
VizBoard is built on Next.js 15.3.2 with the App Router, leveraging modern React 19 features including Server Components, Server Actions, and streaming. The architecture follows a clear separation between server-side data operations and client-side interactions.Core Architecture Patterns
Next.js App Router Structure
The application uses Next.js App Router with route groups for logical organization:Route groups like
(auth) and (homepage) allow for shared layouts without affecting the URL structure.Server Components by Default
VizBoard maximizes the use of React Server Components (RSC) for optimal performance:- Pages are Server Components - All route pages default to server rendering
- Data fetching happens on the server - Direct database queries via Prisma
- Reduced client bundle - Only interactive components are client-side
- Automatic code splitting - Each route loads only necessary code
Example: Dashboard Page Server Component
Example: Dashboard Page Server Component
src/app/projects/[projectId]/dashboard/page.tsx
Server Actions
VizBoard uses Server Actions for all data mutations, providing type-safe server-side operations:Authentication Actions
Located in
src/app/actions/auth/- User registration
- Credential validation
- Password hashing with bcrypt
Project Actions
Located in
src/app/actions/project/- CRUD operations
- Connection management
- Schema introspection
- Validation
Dashboard Actions
Located in
src/app/actions/dashboard/- Widget CRUD
- Widget ordering
- Data fetching
- Table queries
User Actions
Located in
src/app/actions/user/- Profile updates
- Settings management
Example: Server Action with Validation
Example: Server Action with Validation
src/app/actions/project/crud.ts
Authentication Architecture
NextAuth.js v5 Integration
VizBoard uses NextAuth.js v5 (beta) with multiple authentication strategies:- JWT-based sessions for stateless authentication
- OAuth integration (Google, GitHub)
- Credentials-based login with hashed passwords
- Prisma adapter for user/account storage
- Custom callbacks for token enrichment
Database Architecture
Dual Database Pattern
VizBoard employs a unique dual database architecture:Application Database
Prisma + PostgreSQLStores:
- Users & accounts
- Projects & widgets
- Connection metadata (encrypted)
- Schema cache
External Databases
Knex.js + PostgreSQLConnects to:
- User’s external PostgreSQL databases
- Dynamic query execution
- Schema introspection
- Real-time data fetching
Connection Encryption
All external database credentials are encrypted using AES-256-GCM:lib/crypto/crypto.ts
Schema Introspection
VizBoard automatically introspects external database schemas usingknex-schema-inspector:
Auto-Introspection Flow
Auto-Introspection Flow
- Connection Validation - Test connection on creation/update
- Schema Discovery - Extract tables, columns, types, relationships
- Cache Storage - Store schema JSON in
dbConnection.dbSchema - Timestamp Tracking - Update
lastIntrospectionAt - Widget Configuration - Use cached schema for UI dropdowns
State Management
Layered State Architecture
VizBoard uses different state management strategies for different needs:Server State
Server Components + SWRFor:
- Projects list
- Widget data
- User profile
- Automatic revalidation
- Cache management
- Loading states
Client State
Zustand StoresFor:
- Widget dialog forms
- Project draft state
- UI preferences
- Lightweight
- No boilerplate
- DevTools support
Form State
React Hook FormFor:
- Project forms
- Widget configuration
- Settings forms
- Validation with Zod
- Performance
- Error handling
Zustand Store Examples
SWR Data Fetching
For client-side data fetching and caching:hooks/projects/useProjectsWithStore.ts
API Routes vs Server Actions
When to Use Each
Use Server Actions for:
Use Server Actions for:
- Form submissions - Direct form action integration
- Mutations - Create, update, delete operations
- Authentication required - Built-in session access
- Revalidation - Automatic cache invalidation
Use API Routes for:
Use API Routes for:
- Client-side fetching - SWR/fetch integration
- Webhooks - External service callbacks
- Public endpoints - Shared dashboards
- Non-mutation queries - Read-only data
Caching & Revalidation
VizBoard uses Next.js 15’s enhanced caching mechanisms:Cache Strategies
Security Architecture
Credential Encryption
- AES-256-GCM encryption
- Unique IV per entry
- Auth tags for integrity
- Base64-encoded keys
Authentication
- JWT sessions (30 days)
- bcrypt password hashing
- OAuth with Google/GitHub
- Server-side validation
Authorization
- Project ownership checks
- Session validation per action
- Prisma cascade deletes
- User ID verification
Input Validation
- Zod schema validation
- Type-safe Server Actions
- SQL injection prevention
- XSS protection
Performance Optimizations
Database Level
- Connection pooling - Reuse database connections
- Transactions - Atomic operations with
prisma.$transaction - Select optimization - Only fetch required fields
- Parallel introspection -
Promise.allSettledfor multiple connections
Application Level
- Code splitting - Route-based automatic splitting
- Server Components - Zero client-side JavaScript for static content
- Streaming - Progressive rendering with Suspense
- Image optimization - Next.js automatic image optimization
Client Level
- SWR caching - Reduce redundant API calls
- Debouncing - Form inputs and search
- Lazy loading - Widget components loaded on demand
- Optimistic updates - Instant UI feedback
The combination of Server Components, Server Actions, and aggressive caching results in fast page loads and instant interactions.
