Architecture Overview

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Frontend                             │
│              (Next.js 14 App Router + React)                 │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  UI Package  │  │  Chat Window │  │   Dashboard  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└──────────────┬──────────────────────────────────────────────┘
               │
               │ HTTP/REST
               │
┌──────────────▼──────────────────────────────────────────────┐
│                   Backend API Layer                          │
│               (Next.js 14 API Routes)                        │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │   Auth   │  │ Billing  │  │   User   │  │  Tenant  │   │
│  │(NextAuth)│  │          │  │   Mgmt   │  │   Mgmt   │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└──────┬───────────────────────────┬──────────────────────────┘
       │                           │
       │                           │ HTTP/REST
       │                           │
       │                    ┌──────▼──────────────────────────┐
       │                    │   AI Service (Python FastAPI)   │
       │                    │   LiteLLM + FAISS + LangChain   │
       │                    │                                 │
       │                    │  ┌──────────┐  ┌──────────┐    │
       │                    │  │   LLM    │  │ Embeddings│    │
       │                    │  └──────────┘  └──────────┘    │
       │                    └─────────────────────────────────┘
       │
       │
┌──────▼──────────────────────────────────────────────────────┐
│                    Data Layer                                │
│                                                              │
│  ┌──────────────┐          ┌──────────────┐                │
│  │  PostgreSQL  │          │    Redis     │                │
│  │ (via Prisma) │          │  (Upstash)   │                │
│  └──────────────┘          └──────────────┘                │
└─────────────────────────────────────────────────────────────┘

Key Components

Frontend (Next.js 14 App Router)

• Server-Side Rendering: Fast initial page loads with App Router
• Client Components: Interactive UI with React Server Components
• HTTP Client: REST API communication
• Shared UI Package: Reusable components (ChatWindow, etc.)
• Type Safety: Full TypeScript integration

Backend (Next.js API Routes)

• Unified Stack: Next.js handles both frontend SSR and backend API
• Authentication: NextAuth.js for OAuth and credential-based auth
• Multi-Tenancy: Tenant isolation at application and DB level
• API Routes: RESTful endpoints in /app/api directory
• Type-Safe APIs: Shared TypeScript types across frontend and backend

AI Service (Python FastAPI)

• LiteLLM: Unified interface for multiple LLM providers
• OpenAI Integration: GPT models
• Vector Store: FAISS for embeddings and semantic search
• LangChain: Agent orchestration and prompt management
• Async Processing: FastAPI for high-performance async requests

Database Layer

• PostgreSQL: Primary data store (users, tenants, billing, chat history)
• Prisma ORM: Type-safe database access with schema migrations
• Redis (Upstash): Caching and session management
• Connection Pooling: Optimized database connections

Data Flow

Chat Request Flow

1. User sends message via HTTP POST from frontend
2. Next.js API route authenticates via NextAuth session
3. API route validates request and forwards to Python FastAPI service
4. AI Service processes request with LiteLLM
5. Response returned through HTTP response
6. Frontend updates UI with response

Authentication Flow

1. User initiates login via NextAuth.js
2. NextAuth handles OAuth callback or credential validation
3. Session created and stored (JWT or database session)
4. Frontend receives session cookie
5. All subsequent requests include session cookie
6. NextAuth.js middleware validates session on each request

Database Access Flow

1. API route receives request
2. Prisma Client queries PostgreSQL
3. Results cached in Redis (Upstash) when appropriate
4. Response returned to client
5. Cache invalidation on data mutations

Security Considerations

• NextAuth.js for session management and authentication
• OAuth2 for third-party authentication providers
• Multi-tenant data isolation via Prisma row-level filtering
• Rate limiting per tenant and user
• Audit logging for all critical operations
• Environment variables for secrets management
• HTTPS/TLS for all external communication

Scalability

• Horizontal scaling via Vercel serverless functions
• Stateless API routes for easy scaling
• Redis (Upstash) for distributed caching
• Prisma connection pooling
• Async/await throughout the stack
• Edge runtime support for low-latency endpoints
• Database read replicas for high-traffic queries