System Architecture¶

Last Updated: 2025-11-22

Overview¶

AccessALI Customer Portal is a modern full-stack web application built on Next.js 15, designed to provide property buyers with a comprehensive self-service platform for managing their property purchase journey from reservation to turnover.

Architecture Philosophy

The system follows a layered architecture pattern with clear separation of concerns, enabling maintainability, testability, and scalability. The architecture prioritizes developer experience through container-first development and mock API patterns.

High-Level Architecture¶

graph TB
    subgraph "Client Layer"
        Browser[Web Browser]
        Mobile[Mobile Browser]
    end

    subgraph "CDN & Edge"
        Vercel[Vercel Edge Network]
        CDN[Static Assets CDN]
    end

    subgraph "Application Layer - Next.js 15"
        AppRouter[App Router]
        RSC[React Server Components]
        ServerActions[Server Actions]
        APIRoutes[API Routes]
        Middleware[Auth Middleware]
    end

    subgraph "Business Logic Layer"
        UseCases[Use Cases]
        Services[Services]
        Validators[Zod Validators]
    end

    subgraph "Data Access Layer"
        Repositories[Repositories]
        Adapters[Mock/Real Adapters]
        Prisma[Prisma ORM]
    end

    subgraph "Infrastructure Layer"
        DB[(PostgreSQL)]
        Cache[(Redis Cache)]
        BlobStorage[Vercel Blob Storage]
    end

    subgraph "External Systems"
        SAP[SAP System]
        Salesforce[Salesforce]
        SpringCM[SpringCM]
        PaymentGW[Payment Gateway]
    end

    Browser --> Vercel
    Mobile --> Vercel
    Vercel --> AppRouter
    CDN --> Browser

    AppRouter --> RSC
    AppRouter --> ServerActions
    AppRouter --> APIRoutes
    AppRouter --> Middleware

    ServerActions --> UseCases
    APIRoutes --> UseCases

    UseCases --> Services
    UseCases --> Repositories
    Services --> Validators

    Repositories --> Adapters
    Repositories --> Prisma

    Adapters -.Mock Mode.-> UseCases
    Adapters -.Real Mode.-> SAP
    Adapters -.Real Mode.-> Salesforce
    Adapters -.Real Mode.-> SpringCM

    Prisma --> DB
    Services --> Cache
    Services --> BlobStorage
    APIRoutes --> PaymentGW

System Components¶

1. Frontend Layer¶

Technology: Next.js 15 App Router + React 19

The frontend leverages Next.js 15's App Router with React Server Components as the default rendering strategy, providing optimal performance and SEO.

Key Features:

Server Components by Default - Reduces client-side JavaScript
Client Components - Used only for interactivity (forms, real-time updates)
Streaming & Suspense - Progressive content loading
shadcn/ui Components - Accessible, customizable UI primitives

// Example: Server Component (default)
export default async function DashboardPage() {
  const data = await getDashboardData() // Server-side data fetching
  return <DashboardView data={data} />
}

// Example: Client Component (explicit)
'use client'
export function InteractiveForm() {
  const [state, setState] = useState()
  return <form>...</form>
}

2. Application Layer¶

Technology: Next.js Server Actions + API Routes

Handles HTTP requests, authentication, and orchestrates business logic.

Components:

Server Actions (src/app/actions/) - Type-safe server functions for mutations/queries
API Routes (src/app/api/) - RESTful endpoints for webhooks, file uploads
Middleware (middleware.ts) - Auth protection, rate limiting, security headers

Server Actions vs API Routes

Use Server Actions for form submissions and data mutations (preferred)
Use API Routes for webhooks, file uploads, and third-party integrations

3. Business Logic Layer¶

Technology: TypeScript + Zod

Contains core business logic independent of HTTP concerns.

Components:

Use Cases (src/lib/use-cases/) - Business logic orchestration
Services (src/lib/services/) - Cross-cutting concerns (email, file upload, notifications)
Validators (src/lib/validators/) - Input validation with Zod schemas

// Use Case Pattern
export async function getDashboardUseCase(userId: string) {
  // Orchestrate multiple repositories
  const properties = await propertyRepository.findByUserId(userId)
  const payments = await paymentRepository.findByUserId(userId)

  // Business logic
  return {
    properties,
    upcomingPayments: payments.filter(p => p.status === 'PENDING'),
    totalOwed: payments.reduce((sum, p) => sum + p.amount, 0)
  }
}

4. Data Access Layer¶

Technology: Prisma ORM + PostgreSQL

Provides type-safe database access and external API integration.

Components:

Repositories (src/lib/repositories/) - Database operations via Prisma
Adapters (src/lib/adapters/) - Mock/Real API switching
Mocks (src/lib/mocks/) - Development data

Mock API Pattern

The adapter pattern allows seamless switching between mock and real APIs via environment variables, enabling development without external dependencies.

// Adapter Pattern
export const sapAdapter = createAdapter(
  SAPMock,           // Mock implementation
  SAPClient,         // Real implementation
  'USE_MOCK_SAP'     // Environment flag
)

// Usage (same code works with both!)
const contract = await sapAdapter.getContract(id)

5. Infrastructure Layer¶

Technology: PostgreSQL + Redis + Vercel Blob

Handles data persistence and caching.

Components:

PostgreSQL 16 - Primary relational database (Neon)
Redis 7 - Session storage and caching (Upstash)
Vercel Blob Storage - File storage for documents and images

Data Flow¶

Request Flow (Server Actions)¶

sequenceDiagram
    participant User
    participant Next.js
    participant ServerAction
    participant UseCase
    participant Repository
    participant Database

    User->>Next.js: Submit Form
    Next.js->>ServerAction: Call Server Action
    ServerAction->>ServerAction: Authenticate
    ServerAction->>ServerAction: Validate Input (Zod)
    ServerAction->>UseCase: Execute Business Logic
    UseCase->>Repository: Query/Mutate Data
    Repository->>Database: Execute SQL (Prisma)
    Database-->>Repository: Results
    Repository-->>UseCase: Domain Models
    UseCase-->>ServerAction: Success/Error
    ServerAction->>ServerAction: Revalidate Cache
    ServerAction-->>Next.js: Response
    Next.js-->>User: Updated UI

Request Flow (API Routes)¶

sequenceDiagram
    participant Client
    participant APIRoute
    participant Service
    participant External

    Client->>APIRoute: POST /api/upload
    APIRoute->>APIRoute: Validate Auth
    APIRoute->>Service: Upload File
    Service->>External: Store in Blob Storage
    External-->>Service: File URL
    Service-->>APIRoute: Upload Result
    APIRoute-->>Client: JSON Response

Technology Stack¶

Core Technologies¶

Layer	Technology	Version	Purpose
Frontend Framework	Next.js	15.5.6	React framework with App Router
UI Library	React	19.2.0	Component-based UI
Language	TypeScript	5.7.2	Type-safe development
UI Components	shadcn/ui	Latest	Radix UI + Tailwind CSS
Styling	Tailwind CSS	3.4.18	Utility-first CSS
Database	PostgreSQL	16	Relational database
ORM	Prisma	6.2.1	Type-safe database client
Authentication	NextAuth.js	v5 beta	OAuth + Credentials auth
Cache	Redis	7	Session storage & caching
Container	Docker	Latest	Development environment

Development Tools¶

Package Manager: pnpm 9.15.0
Type Checking: TypeScript strict mode
Linting: ESLint with Next.js config
Formatting: Prettier (via ESLint)
Testing: Jest + React Testing Library
E2E Testing: Playwright (planned)

Deployment Architecture¶

Production Environment (Vercel)¶

graph LR
    subgraph "Vercel Platform"
        Edge[Edge Network]
        Functions[Serverless Functions]
        ISR[Incremental Static Regeneration]
    end

    subgraph "External Services"
        NeonDB[(Neon PostgreSQL)]
        Upstash[(Upstash Redis)]
        BlobStorage[Vercel Blob]
    end

    Edge --> Functions
    Edge --> ISR
    Functions --> NeonDB
    Functions --> Upstash
    Functions --> BlobStorage

Deployment Strategy:

Hosting: Vercel (Automatic deployments from GitHub)
Database: Neon PostgreSQL (Serverless PostgreSQL)
Cache: Upstash Redis (Serverless Redis)
Storage: Vercel Blob Storage
CI/CD: GitHub Actions → Vercel deployment

Development Environment (Docker)¶

graph TB
    subgraph "Docker Compose"
        App[Next.js App<br/>Port 3000]
        DB[(PostgreSQL<br/>Port 5432)]
        RedisCache[(Redis<br/>Port 6379)]
        Studio[Prisma Studio<br/>Port 5555]
    end

    App --> DB
    App --> RedisCache
    Studio --> DB

Security Architecture¶

Authentication & Authorization¶

NextAuth.js v5 - Session management
JWT Tokens - Stateless authentication
Role-Based Access Control (RBAC) - User, Admin, Support roles
OAuth Providers - Google, Facebook
Email/Password - Credentials provider with bcrypt hashing

Security Layers¶

graph TB
    Request[Incoming Request]
    Middleware[Auth Middleware]
    CORS[CORS Policy]
    CSRF[CSRF Protection]
    RateLimit[Rate Limiting]
    Input[Input Validation]
    Auth[Authorization Check]
    Action[Execute Action]

    Request --> Middleware
    Middleware --> CORS
    CORS --> CSRF
    CSRF --> RateLimit
    RateLimit --> Input
    Input --> Auth
    Auth --> Action

Security Best Practices¶

Input Validation - Zod schemas at all entry points
SQL Injection Prevention - Parameterized queries via Prisma
XSS Prevention - React automatic escaping + CSP headers
CSRF Protection - Built-in Next.js CSRF tokens
Rate Limiting - Redis-based rate limiter
Security Headers - Helmet.js configuration
Secrets Management - Environment variables, never committed

Scalability Considerations¶

Horizontal Scaling¶

Stateless Functions - Next.js serverless functions scale automatically
Database Connection Pooling - Prisma connection pooling + PgBouncer
CDN Distribution - Static assets served via Vercel Edge Network
Caching Strategy - Multi-layer caching (browser, CDN, Redis)

Performance Optimizations¶

graph LR
    subgraph "Caching Layers"
        Browser[Browser Cache<br/>Static Assets]
        CDN[CDN Cache<br/>Pages & Images]
        Redis[Redis Cache<br/>API Responses]
        DB[Database<br/>Source of Truth]
    end

    Browser --> CDN
    CDN --> Redis
    Redis --> DB

Optimization Strategies:

React Server Components - Reduce client-side JavaScript
Image Optimization - Next.js Image component with automatic optimization
Code Splitting - Automatic route-based code splitting
Database Indexing - Strategic indexes on frequently queried columns
Query Optimization - Efficient Prisma queries with proper relations

Integration Points¶

External System Integrations¶

System	Purpose	Integration Method	Status
SAP	Contract & payment data	REST API (Mock ready)	Planned
Salesforce	Customer relationship data	REST API (Mock ready)	Planned
SpringCM	Document management	REST API (Mock ready)	Planned
Payment Gateway	Payment processing	Webhook + API	Planned
Email Service	Transactional emails	SMTP / SendGrid	Planned

Adapter Pattern for Integrations¶

All external integrations use the adapter pattern, allowing development with mocks and seamless transition to production.

// Environment-based switching
USE_MOCK_SAP="true"   // Development
USE_MOCK_SAP="false"  // Production

// Code remains the same
const data = await sapAdapter.getContract(id)

Monitoring & Observability¶

Application Monitoring (Planned)¶

Error Tracking - Sentry for error monitoring
Performance Monitoring - Vercel Analytics
Logging - Structured logging with Winston
Metrics - Custom metrics via Vercel

Health Checks¶

Database Health - Prisma connection check
Redis Health - Redis ping check
API Health - External API availability checks

Layered Architecture - Detailed layer breakdown
Database Schema - Complete database documentation
Security - Security implementation details
Mock API Pattern - Mock/Real API switching

Next Steps¶

Review Database Schema to understand data models
Explore Layered Architecture for code organization
Check Security for security implementation guidelines

System Architecture¶

Overview¶

High-Level Architecture¶

System Components¶

1. Frontend Layer¶

2. Application Layer¶

3. Business Logic Layer¶

4. Data Access Layer¶

5. Infrastructure Layer¶

Data Flow¶

Request Flow (Server Actions)¶

Request Flow (API Routes)¶

Technology Stack¶

Core Technologies¶

Development Tools¶

Deployment Architecture¶

Production Environment (Vercel)¶

Development Environment (Docker)¶

Security Architecture¶

Authentication & Authorization¶

Security Layers¶

Security Best Practices¶

Scalability Considerations¶

Horizontal Scaling¶

Performance Optimizations¶

Integration Points¶

External System Integrations¶

Adapter Pattern for Integrations¶

Monitoring & Observability¶

Application Monitoring (Planned)¶

Health Checks¶

Related Documentation¶

Next Steps¶