Architecture Overview

AccessALI follows modern architectural patterns and best practices for scalability, maintainability, and developer experience.

System Architecture

graph TB
    subgraph "Users"
        U[10,000+ Concurrent Users]
    end

    subgraph "Edge Layer"
        CDN[Vercel Edge Network<br/>CDN + DDoS Protection]
    end

    subgraph "Application Layer"
        NEXT[Next.js 15 Full-Stack App]
        RSC[React Server Components]
        SA[Server Actions]
        API[API Routes]
        AUTH[NextAuth.js v5]
    end

    subgraph "Data Layer"
        PRISMA[Prisma ORM]
        ADAPTERS[API Adapters]
        MOCK[Mock Implementations]
        REAL[Real Integrations]
    end

    subgraph "Infrastructure"
        DB[(PostgreSQL 16<br/>Neon DB)]
        CACHE[(Redis 7<br/>Upstash)]
    end

    U --> CDN
    CDN --> NEXT
    NEXT --> RSC
    NEXT --> SA
    NEXT --> API
    NEXT --> AUTH
    SA --> PRISMA
    SA --> ADAPTERS
    ADAPTERS --> MOCK
    ADAPTERS --> REAL
    PRISMA --> DB
    SA --> CACHE

Key Architectural Decisions

1. Full-Stack Next.js

Decision: Use Next.js 15 with App Router for both frontend and backend.

Why? - Single codebase reduces complexity - Server Actions eliminate REST API boilerplate - Type-safe end-to-end with TypeScript - Native Vercel deployment - Modern developer experience

Trade-offs:

• ✅ Simpler architecture, faster development
• ❌ Tight coupling to React ecosystem

2. Layered Architecture

Decision: Implement clear separation of concerns with four distinct layers.

Layers:

1. Presentation - React components, UI
2. Application - Server Actions, API routes
3. Domain - Business logic, use cases
4. Infrastructure - Data access, external APIs

Benefits:

• Clear boundaries between concerns
• Easy to test each layer independently
• Flexible to swap implementations
• Better code organization

3. Mock API Adapter Pattern

Decision: Environment-switchable adapters for external APIs.

Why? - Develop without waiting for real APIs - Seamless migration path - Parallel testing during transition - No code changes when switching modes

See: Mock API Pattern

4. PostgreSQL + Prisma ORM

Decision: Use PostgreSQL with Prisma for type-safe database access.

Why? - ACID compliance for financial transactions - Excellent type safety with Prisma - Serverless PostgreSQL with Neon DB - Built-in connection pooling

See: Database Schema

5. NextAuth.js Authentication

Decision: Use NextAuth.js v5 for authentication.

Features:

• Multiple providers (Email, Google, Facebook)
• JWT sessions with HTTP-only cookies
• Role-based access control (RBAC)
• CSRF protection built-in

See: Security Architecture

Technology Stack

Frontend

Technology	Version	Purpose
Next.js	15.5.6	React framework with App Router
React	19.2.0	UI library with Server Components
TypeScript	5.7.2	Type safety
Tailwind CSS	3.4.18	Utility-first CSS framework
shadcn/ui	Latest	High-quality UI components
Zod	3.25.76	Schema validation

Backend

Technology	Version	Purpose
Next.js Server Actions	15.5.6	Server-side data mutations
NextAuth.js	v5.0.0-beta.25	Authentication
Prisma	6.2.1	Type-safe ORM
PostgreSQL	16	Relational database
Redis	7	Caching layer

DevOps

Technology	Version	Purpose
Docker	Latest	Containerization
Docker Compose	2.0+	Local orchestration
Kubernetes	1.28+	Production orchestration
Vercel	-	Serverless deployment
GitHub Actions	-	CI/CD

Scalability Strategy

Target Performance

AccessALI is designed to handle 10,000+ concurrent users with:

• TTFB (Time to First Byte): < 200ms
• LCP (Largest Contentful Paint): < 2.5s
• CLS (Cumulative Layout Shift): < 0.1
• TTI (Time to Interactive): < 3.5s

Horizontal Scaling

• Vercel auto-scales serverless functions
• No manual configuration required
• Pay per request (cost-effective)

Caching Strategy

1. Edge Caching (Vercel CDN)

   • Static assets: 1 year TTL
   • Images, fonts, CSS, JavaScript

2. API Caching (Redis)

   • User profiles: 10 minutes
   • Property data: 5 minutes
   • Construction updates: 1 hour

3. Database Caching (PgBouncer)

   • Connection pooling
   • Reduces database overhead

Security Architecture

Defense in Depth

graph LR
    A[User] --> B[HTTPS/TLS]
    B --> C[Vercel Edge<br/>DDoS Protection]
    C --> D[Next.js App<br/>CSRF Protection]
    D --> E[NextAuth.js<br/>Authentication]
    E --> F[Middleware<br/>Authorization]
    F --> G[Prisma ORM<br/>SQL Injection Prevention]
    G --> H[Database<br/>Encrypted at Rest]

Security Measures

Layer	Implementation	Status
Transport	HTTPS/TLS	✅ Automatic (Vercel)
Application	CSRF Protection	✅ Built-in (Server Actions)
Authentication	NextAuth.js JWT	✅ Configured
Authorization	RBAC Middleware	✅ Implemented
Input Validation	Zod Schemas	✅ Required
SQL Injection	Prisma Parameterized Queries	✅ Built-in
XSS Prevention	React Auto-escaping + CSP	✅ Built-in
Password Hashing	bcryptjs (12 rounds)	✅ Configured
Rate Limiting	Vercel Edge + Middleware	🚧 Planned

Development Workflow

Local Development

graph LR
    A[Developer] --> B[Edit Code]
    B --> C[Hot Reload]
    C --> D[Browser Update]
    D --> E[Test Locally]
    E --> F{Good?}
    F -->|No| B
    F -->|Yes| G[Commit]
    G --> H[Push to GitHub]
    H --> I[CI/CD Pipeline]
    I --> J[Deploy to Preview]

Deployment Pipeline

graph TD
    A[Feature Branch] -->|Push| B[Preview Deployment]
    C[Develop Branch] -->|Merge| D[Staging Deployment]
    E[Main Branch] -->|Merge| F[Production Deployment]

    B --> G[Run Tests]
    D --> G
    F --> G

    G -->|Pass| H[Deploy]
    G -->|Fail| I[Notify Team]

File Structure

accessali/
├── src/
│   ├── app/                      # Next.js App Router
│   │   ├── (auth)/               # Authentication pages
│   │   ├── (dashboard)/          # Protected pages
│   │   ├── actions/              # Server Actions
│   │   ├── api/                  # API routes
│   │   └── layout.tsx            # Root layout
│   │
│   ├── components/               # React components
│   │   ├── ui/                   # shadcn/ui primitives
│   │   └── [feature]/            # Feature components
│   │
│   └── lib/                      # Core business logic
│       ├── adapters/             # API adapters
│       ├── use-cases/            # Business logic
│       ├── repositories/         # Data access
│       ├── services/             # Business services
│       ├── validators/           # Zod schemas
│       └── mocks/                # Mock implementations
│
├── prisma/                       # Database
│   ├── schema.prisma             # Schema definition
│   └── migrations/               # Migration history
│
├── docker/                       # Docker configuration
├── k8s/                          # Kubernetes manifests
└── documents/                    # Documentation

Learn More

• Layered Architecture - Detailed layer responsibilities
• Mock API Pattern - Adapter implementation
• Database Schema - Data model
• Security - Security architecture
• System Architecture - Detailed system design