EASE Architecture

Welcome to the EASE architecture documentation. This section provides comprehensive coverage of the platform's architecture, design decisions, and implementation patterns.

What You'll Learn

This guide covers the complete EASE platform architecture, from high-level system design to detailed implementation patterns.

Architecture Topics

📐 System Design

• Architecture Overview - High-level system architecture, technology stack, and component interactions
• Multi-Tenancy Strategies - Three tenant isolation strategies: PDB, Schema-per-Tenant, and Shared Schema with VPD

🔐 Security Architecture

• JWT-based Authentication - Token-based auth with refresh tokens
• RBAC Implementation - Three-layer role-based access control
• SSO Integration - SAML, OAuth, and OpenID Connect support
• API Gateway Security - Kong-based security policies

💾 Data Architecture

• Oracle Database Design - Schema design, VPD policies, and partitioning
• Multi-Tenancy Data Isolation - PDB, schema-level, and row-level strategies
• Caching Strategy - Redis for sessions and API responses
• Search Integration - PostgreSQL for full-text search and AI embeddings

🚀 Service Architecture

• Microservices Design - .NET Core service patterns
• API Gateway (Kong) - Routing, auth, rate limiting, and integration
• Real-time Services - Node.js WebSocket services
• AI Services - FastAPI-based BACH chatbot integration

🎨 Frontend Architecture

• Next.js Architecture - App Router, SSR, and static generation
• Component Design - Reusable UI components with shadcn/ui
• State Management - Client and server state patterns
• Authentication Flow - JWT cookie-based authentication

📊 Observability

• Logging Strategy - Centralized logging with ELK stack
• Metrics & Monitoring - Prometheus and Grafana
• Distributed Tracing - Jaeger for request tracing
• Health Checks - Service health monitoring

Architecture Principles

EASE is built on these core principles:

1. Defense in Depth

Security at multiple layers:

• Network (WAF, DDoS protection)
• Gateway (JWT validation, rate limiting)
• Application (input validation, RBAC)
• Database (VPD, TDE, audit logging)

2. Multi-Tenancy First

Every component designed for tenant isolation:

• Automatic tenant context injection
• VPD for database-level isolation
• Tenant-scoped caching
• Isolated logging and metrics

3. Developer Experience

Focus on productivity:

• Base classes for common patterns
• Automatic OpenAPI documentation
• Comprehensive error handling
• Self-documenting code

4. Performance & Scalability

Built for enterprise scale:

• Horizontal scaling for all services
• Oracle RAC for database clustering
• Redis for distributed caching
• CDN for static assets

5. Hybrid Technology Strategy

Leverage existing investments:

• .NET Core for Oracle integration
• Next.js for modern frontend
• Kong for API gateway
• FastAPI for AI workloads

System Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                     Users / Mobile Apps                      │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTPS
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                      Kong API Gateway                        │
│  • Routing            • Rate Limiting    • OAuth/JWT         │
│  • Load Balancing     • Caching         • SAP/ERP Proxy     │
└────┬──────────┬──────────┬──────────┬────────────┬──────────┘
     │          │          │          │            │
     ▼          ▼          ▼          ▼            ▼
┌─────────┐ ┌────────┐ ┌──────┐ ┌─────────┐ ┌────────────┐
│ Next.js │ │  .NET  │ │Node.js│ │ FastAPI│ │  External  │
│Frontend │ │  Core  │ │WebSocket│ │  BACH  │ │  Systems   │
│         │ │Services│ │       │ │Chatbot │ │ (SAP, ERP) │
└─────────┘ └────┬───┘ └───┬───┘ └────┬────┘ └────────────┘
                 │         │          │
                 └─────┬───┴──────────┘
                       ▼
            ┌──────────────────────┐
            │    Data Layer        │
            ├──────────────────────┤
            │ • Oracle (Primary)   │
            │ • Redis (Cache)      │
            │ • PostgreSQL (AI)    │
            └──────────────────────┘

Technology Stack

Key Architectural Patterns

Repository Pattern

All data access through repositories for testability and maintainability.

public interface IBookingRepository
{
    Task<IEnumerable<Booking>> GetAllAsync(int tenantId);
    Task<Booking> GetByIdAsync(int id, int tenantId);
    Task<Booking> CreateAsync(Booking booking);
}

Service Layer Pattern

Business logic separated from controllers.

public class BookingService : IBookingService
{
    private readonly IBookingRepository _repository;

    public async Task<Booking> CreateBookingAsync(CreateBookingDto dto, int tenantId)
    {
        // Business logic here
        return await _repository.CreateAsync(booking);
    }
}

Dependency Injection

All components use DI for loose coupling and testability.

builder.Services.AddScoped<IBookingRepository, BookingRepository>();
builder.Services.AddScoped<IBookingService, BookingService>();

Base Classes

Common functionality in base classes to reduce boilerplate.

public abstract class BaseController : ControllerBase
{
    protected int TenantId => GetTenantIdFromClaims();
    protected int UserId => GetUserIdFromClaims();
}

Data Flow Examples

API Request Flow

1. User → Next.js Frontend (with JWT cookie)
2. Frontend → Kong Gateway
3. Kong validates JWT, extracts claims
4. Kong → .NET Service (with headers: tenant_id, user_id)
5. Service extracts context from claims
6. Service → Repository with tenant context
7. Repository → Oracle (VPD auto-filters by tenant)
8. Oracle → Repository → Service → Kong → Frontend → User

Authentication Flow

1. User submits credentials
2. Next.js → Kong → AuthService
3. AuthService validates against Oracle
4. AuthService loads user roles/permissions
5. AuthService generates JWT with claims
6. Kong sets secure HTTP-only cookie
7. User redirected to dashboard

Chatbot Query Flow

1. User presses Ctrl+/
2. Frontend → FastAPI Chatbot Service
3. Chatbot extracts context (page, user role)
4. Chatbot searches docs (RAG with PostgreSQL)
5. Chatbot builds enriched prompt
6. Chatbot → BACH API
7. BACH → Chatbot → Frontend → User

Quick Links

Essential Reading

• Architecture Overview - Start here for the big picture
• Multi-Tenancy Guide - Understanding tenant isolation
• Your First Component - Hands-on tutorial

Deep Dives

• Security Architecture - Defense in depth strategy (coming soon)
• Performance Optimization - Scaling strategies (coming soon)
• Deployment Guide - Production deployment (coming soon)

Architecture Decision Records (ADRs)

For detailed architectural decisions, see the ADR documents:

• EASE Enterprise Architecture ADR - Complete platform architecture
• MCP Client Orchestration ADR - AI/Chatbot architecture
• Implementation Instructions - Build and deployment guide

Questions?

• 🤖 Press Ctrl+/ to ask BACH about architecture
• 📚 Read Architecture Overview
• 💻 Try Building Your First Component
• 📖 Browse Code Examples (coming soon)

Ready to dive deeper? Start with the Architecture Overview →