System Architecture

This document provides a comprehensive overview of the architecture, design decisions, and implementation patterns.

Table of Contents

• Overview

• Technology Stack

• Architecture Patterns

• Data Flow

• Authentication & Authorization

• Component Architecture

• State Management

• Routing

• Security

• Performance Considerations

• Scalability

Overview

This a production-grade, architectural process built with modern web technologies. It follows a Server-First architecture using Next.js 15+ App Router, prioritizing server-side rendering and server actions for optimal performance and security.

Key Principles

1. Server-First: Default to Server Components, use Client Components only when necessary

2. Type Safety: Leverage TypeScript throughout the stack

3. Security First: Multiple layers of authentication and authorization

4. Performance: Minimize client-side JavaScript, leverage server rendering

5. Developer Experience: Clear patterns, consistent conventions, comprehensive documentation

Technology Stack

Core Framework

• Next.js 15+ (16.1.3): React framework with App Router

  • Server Components by default

  • Server Actions for mutations

  • File-based routing

  • API routes for NextAuth

UI Layer

• React 18+: UI library

  • Server Components for static/dynamic content

  • Client Components for interactivity

• Chakra UI v3: Component library and design system

  • Headless UI primitives

  • Accessible components

  • Custom theme with brand colors

Authentication & Authorization

• NextAuth: Authentication solution

  • Credentials provider

  • JWT strategy

  • Session management

• bcryptjs: Password hashing

• RBAC: Role-based access control (admin/manager/viewer)

Language & Tooling

• TypeScript 5+: Type safety and better DX

• ESLint: Code linting

• Prettier: Code formatting

• Turbopack: Next.js dev server bundler

Development

• Node.js 18+: Runtime environment

• npm: Package manager

Architecture Patterns

1. Server-First Rendering

Pattern: Use Server Components by default, Client Components only when needed

Rationale:

• Reduces client-side JavaScript bundle

• Improves SEO and initial page load

• Better security (sensitive data stays on server)

• Simpler data fetching patterns

Implementation:

// Server Component (default)
export default async function DashboardPage() {
  const session = await auth();
  const data = await fetchData();
  return <DashboardView data={data} />;
}

// Client Component (when needed)
"use client";
export function InteractiveButton() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

When to use Client Components:

• Event handlers (onClick, onChange)

• React hooks (useState, useEffect)

• Browser APIs (localStorage, window)

• Interactive UI elements

2. Server Actions Pattern

Pattern: Use Server Actions for all data mutations

Rationale:

• Eliminates need for API routes

• Type-safe function calls

• Automatic form handling

• Progressive enhancement

• Direct database access without client-side fetch

Implementation:

// src/app/actions/users.ts
"use server";

import { auth } from "@/lib/auth/config";
import type { ActionResult } from "@/types";

export async function deleteUser(userId: string): Promise<ActionResult<void>> {
  // 1. Authenticate
  const session = await auth();
  if (!session?.user) {
    return { success: false, error: "Unauthorized" };
  }

  // 2. Authorize
  if (!canManageUsers(session.user.role)) {
    return { success: false, error: "Forbidden" };
  }

  // 3. Validate
  if (!userId) {
    return { success: false, error: "Invalid user ID" };
  }

  // 4. Execute
  try {
    await db.users.delete({ where: { id: userId } });
    return { success: true, data: undefined };
  } catch (error) {
    return { success: false, error: "Failed to delete user" };
  }
}

Usage in Component:

// Client Component
import { deleteUser } from "@/app/actions/users";

export function DeleteButton({ userId }: { userId: string }) {
  const handleDelete = async () => {
    const result = await deleteUser(userId);
    if (result.success) {
      toast.success("User deleted");
    } else {
      toast.error(result.error);
    }
  };

  return <button onClick={handleDelete}>Delete</button>;
}

3. Layered Architecture

Pattern: Clear separation of concerns with defined layers

┌─────────────────────────────────────┐
│   Presentation Layer                │
│   (Components, Pages)               │
├─────────────────────────────────────┤
│   Business Logic Layer              │
│   (Server Actions, Auth)            │
├─────────────────────────────────────┤
│   Data Access Layer                 │
│   (Database, APIs)                  │
└─────────────────────────────────────┘

Responsibilities:

1. Presentation Layer (src/components/, src/app/)

   • UI rendering

   • User interactions

   • Client-side state (React state)

   • No business logic

2. Business Logic Layer (src/app/actions/, src/lib/auth/)

   • Authentication/authorization

   • Data validation

   • Business rules

   • Error handling

3. Data Access Layer (Future: src/lib/db/)

   • Database queries

   • External API calls

   • Data transformation

4. Permission-Based Access Control

Pattern: Centralized permission checks with role-based rules

Implementation:

// src/lib/constants/permissions.ts
export const PERMISSIONS = {
  // User management
  CAN_MANAGE_USERS: ["admin"],
  CAN_VIEW_USERS: ["admin", "manager"],

  // Analytics
  CAN_VIEW_ANALYTICS: ["admin", "manager", "viewer"],

  // Settings
  CAN_MANAGE_SETTINGS: ["admin"],
} as const;

export function canManageUsers(role: UserRole): boolean {
  return PERMISSIONS.CAN_MANAGE_USERS.includes(role);
}

Usage:

// In Server Action
if (!canManageUsers(session.user.role)) {
  return { success: false, error: "Forbidden" };
}

// In Server Component
if (session.user.role !== "admin") {
  redirect("/dashboard");
}

5. Error Handling Pattern

Pattern: Consistent ActionResult<T> type for all operations

Rationale:

• Type-safe error handling

• Predictable API surface

• Easy error propagation

• Better user experience

Implementation:

// Type definition
type ActionResult<T> =
  | { success: true; data: T }
  | { success: false; error: string };

// Usage
export async function getUser(id: string): Promise<ActionResult<User>> {
  try {
    const user = await db.users.findUnique({ where: { id } });
    if (!user) {
      return { success: false, error: "User not found" };
    }
    return { success: true, data: user };
  } catch (error) {
    return { success: false, error: "Failed to fetch user" };
  }
}

Data Flow

1. Page Load Flow

User Request
    ↓
Middleware (auth check)
    ↓
Server Component renders
    ↓
Fetch session (server-side)
    ↓
Fetch data (Server Actions)
    ↓
Render HTML with data
    ↓
Send to client

2. Form Submission Flow

User fills form
    ↓
Submits form
    ↓
Server Action invoked
    ↓
Validate request
    ↓
Check permissions
    ↓
Execute operation
    ↓
Return ActionResult
    ↓
Update UI based on result

3. Authentication Flow

User enters credentials
    ↓
POST to /api/auth/signin
    ↓
NextAuth authorize() called
    ↓
Bcrypt verifies password
    ↓
JWT callback adds role/id
    ↓
Session callback creates session
    ↓
Session cookie set
    ↓
Redirect to dashboard

Authentication & Authorization

Architecture

┌──────────────────────────────────────┐
│  Middleware (Route Protection)       │
│  - Checks session before routing     │
│  - Redirects unauthenticated users   │
└──────────────────────────────────────┘
                ↓
┌──────────────────────────────────────┐
│  Server Components (Page-level)      │
│  - Check session on render           │
│  - Redirect unauthorized roles       │
└──────────────────────────────────────┘
                ↓
┌──────────────────────────────────────┐
│  Server Actions (Operation-level)    │
│  - Check session on execution        │
│  - Verify permissions                │
│  - Return errors if unauthorized     │
└──────────────────────────────────────┘

Multi-Layer Security

1. Middleware Layer (src/middleware.ts)

   • First line of defense

   • Route-level protection

   • Redirects unauthenticated users

2. Component Layer (Server Components)

   • Page-level authorization

   • Redirects unauthorized roles

   • Hides UI elements

3. Action Layer (Server Actions)

   • Operation-level authorization

   • Permission checks

   • Final security gate

Defense in Depth: Even if one layer is bypassed, others still protect the system.

Session Management

• Strategy: JWT with credentials provider

• Storage: HttpOnly cookies (secure, XSS-resistant)

• Duration: Session-based (expires on browser close)

• Refresh: Automatic token refresh

Component Architecture

Component Hierarchy

app/layout.tsx (Root Layout)
    ├── Providers (Chakra, Session)
    │   ├── app/(dashboard)/layout.tsx (Dashboard Layout)
    │   │   ├── Sidebar
    │   │   ├── Header
    │   │   └── {children}
    │   │       ├── dashboard/page.tsx
    │   │       ├── users/page.tsx
    │   │       ├── analytics/page.tsx
    │   │       └── settings/page.tsx
    │   └── login/page.tsx

Component Types

1. Layout Components (src/components/layout/)

   • Header: Top navigation bar

   • Sidebar: Left navigation menu

   • Page layouts with consistent structure

2. UI Components (src/components/ui/)

   • Button: Primary/secondary/ghost variants

   • Input: Text/email/password inputs

   • Card: Content containers

3. Navigation Components (src/components/navigation/)

   • BrandLogo: Logo with light/dark variants

Component Patterns

Composition over Inheritance:

// Compose small components
<Card>
  <CardHeader title="Users" />
  <CardBody>
    <UserList users={users} />
  </CardBody>
</Card>

Props Interface:

interface ButtonProps {
  variant?: "primary" | "secondary" | "ghost";
  size?: "sm" | "md" | "lg";
  isLoading?: boolean;
  onClick?: () => void;
  children: React.ReactNode;
}

State Management

Client State

When to use: Component-level UI state

Tools: React hooks (useState, useReducer)

Examples:

• Form inputs

• Toggle states

• Modal open/close

• Loading states

Pattern:

"use client";
export function LoginForm() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [isLoading, setIsLoading] = useState(false);

  const handleSubmit = async () => {
    setIsLoading(true);
    await signIn(email, password);
    setIsLoading(false);
  };
}

Server State

When to use: Data from server, shared across components

Tools: Server Components, Server Actions

Examples:

• User data

• Dashboard stats

• Analytics data

Pattern:

// Server Component fetches data
export default async function DashboardPage() {
  const session = await auth();
  const stats = await getDashboardStats();
  return <DashboardView stats={stats} />;
}

Session State

Management: NextAuth session

Server-side:

import { auth } from "@/lib/auth/config";

const session = await auth();

Client-side:

import { useSession } from "next-auth/react";

const { data: session, status } = useSession();

Routing

File-Based Routing

src/app/
├── (dashboard)/           # Route group (doesn't affect URL)
│   ├── dashboard/
│   │   └── page.tsx      → /dashboard
│   ├── users/
│   │   └── page.tsx      → /users
│   ├── analytics/
│   │   └── page.tsx      → /analytics
│   └── settings/
│       └── page.tsx      → /settings
├── login/
│   └── page.tsx          → /login
└── page.tsx              → /

Protected Routes

Middleware (src/middleware.ts):

export default auth((req) => {
  const isAuthenticated = !!req.auth;
  const isProtectedRoute = PROTECTED_ROUTES.some(route =>
    req.nextUrl.pathname.startsWith(route)
  );

  if (isProtectedRoute && !isAuthenticated) {
    return NextResponse.redirect(new URL("/login", req.url));
  }
});

Role-Based Routes

Server Component check:

export default async function AdminPage() {
  const session = await auth();

  if (session?.user?.role !== "admin") {
    redirect("/dashboard");
  }

  return <AdminContent />;
}

Security

Authentication

• Password Hashing: bcrypt with salt rounds

• Session Storage: HttpOnly, secure cookies

• CSRF Protection: Built-in to NextAuth

• Session Expiration: Automatic on browser close

Authorization

• Role-Based Access: Three roles (admin, manager, viewer)

• Permission Checks: Server-side verification

• Route Protection: Middleware + component-level checks

• Action Protection: Every Server Action verifies permissions

Data Security

• No Sensitive Data in Client: Server Components keep data on server

• Input Validation: Validate all user inputs

• SQL Injection: Use parameterized queries (when database is added)

• XSS Protection: React auto-escapes content

Best Practices

1. Never Trust Client Data: Always validate on server

2. Principle of Least Privilege: Users only access what they need

3. Defense in Depth: Multiple security layers

4. Secure Defaults: Deny by default, allow by exception

5. Audit Logging: Log important actions (future enhancement)

Performance Considerations

Server-Side Rendering Benefits

• Faster Initial Load: HTML rendered on server

• Better SEO: Search engines can crawl content

• Smaller Bundle Size: Less JavaScript sent to client

• Time to Interactive: Faster page becomes interactive

Code Splitting

• Automatic: Next.js splits by route

• Dynamic Imports: Load heavy components on demand

• Client Components: Only when needed

Caching Strategy

• Static Assets: CDN caching

• API Routes: Cache headers where appropriate

• Server Components: Automatic caching with revalidation

• Images: Next.js Image optimization

Optimization Techniques

1. Minimize Client Components: Use Server Components by default

2. Lazy Loading: Load heavy components dynamically

3. Image Optimization: Use Next.js Image component

4. Bundle Analysis: Monitor bundle size

5. Server Actions: Reduce client-side JavaScript

Scalability

Database Considerations

Current State: Demo data in memory

Future: Prisma ORM with PostgreSQL

Preparation:

• Server Actions ready for database integration

• Type definitions prepared

• Permission system in place

Horizontal Scaling

• Stateless: Server Actions are stateless

• Session Storage: Can move to Redis/JWT

• CDN Ready: Static assets can be cached

• API Layer: Ready for microservices migration

Vertical Scaling

• Performance: Server rendering reduces load

• Memory: Efficient data fetching

• CPU: Server Actions optimized for speed

Monitoring

Future Enhancements:

• Error tracking (Sentry)

• Performance monitoring (Vercel Analytics)

• Logging (Winston/Pino)

• Uptime monitoring

Design Decisions

Why Next.js 15+?

• Latest App Router features

• Improved Server Components

• Better TypeScript support

• Turbopack for faster dev builds

• Strong community momentum

Why Chakra UI v3?

• Headless architecture

• Excellent accessibility

• Custom theme system

• TypeScript-first

• Modern design patterns

• Note: Chosen despite v3 being beta (future-proof)

Why Server Actions?

• Eliminates API route boilerplate

• Type-safe data mutations

• Better error handling

• Progressive enhancement

• Simpler mental model

Why Credentials Provider?

• Simple for internal tools

• No OAuth complexity

• Full control over user data

• Easy RBAC implementation

Future Enhancements

Short Term

• Database integration (Prisma + PostgreSQL)

• User registration flow

• Password reset functionality

• Audit logging

• Email notifications

Medium Term

• Advanced analytics dashboard

• Real-time updates (WebSocket/Server-Sent Events)

• File uploads

• Advanced permissions (per-resource)

• Multi-factor authentication

Long Term

• Multi-tenancy support

• API rate limiting

• Advanced caching strategies

• Performance monitoring dashboard

• Automated testing suite

Conclusion

This architecture prioritizes security, performance, and developer experience. The server-first approach leverages modern React/Next.js capabilities to deliver a fast, secure, and maintainable admin dashboard.

The layered architecture ensures clear separation of concerns, while the permission system provides flexible access control. The use of Server Actions simplifies data mutations and reduces boilerplate code.

For implementation details, see CODE_PATTERNS.md. For troubleshooting, see TROUBLESHOOTING.md.