Architecture Documentation

🏗️ Introduction

This document describes the technical architecture and data flow of Alesqui Intelligence, an AI-powered API integration platform designed for enterprise environments.

Target Audience: CISOs, Security Architects, Compliance Officers, IT Directors, Enterprise Technical Evaluators

Alesqui Intelligence enables users to interact with multiple APIs through natural language queries, powered by large language models (LLMs) while maintaining complete data sovereignty through self-hosted deployment.

---

📑 Table of Contents

• Introduction
• High-Level Architecture
  • System Components
• System Architecture
  • Layered Architecture Diagram
  • Architecture Highlights
  • Technical Details
• Data Flow Architecture
  • User Registration & Activation Flow
  • Authentication Flow
  • AI Chat Conversation Flow
• AI Agent Architecture
  • ReAct Pattern Implementation
  • Available Tools
  • Memory Management
• Security Architecture
  • Authentication & Authorization Flow
  • Group-Based API Visibility
  • Password Security
  • API Security (Upstream APIs)
• Scalability & Performance
  • Horizontal Scaling
  • Performance Optimizations
• Monitoring & Observability
  • Health Checks
  • Metrics
  • Logging
  • Audit Logging
• Deployment Architecture
  • Recommended Production Deployment
  • High Availability Setup
• Network Security
  • Private Network Deployment
  • Azure OpenAI Option
• Disaster Recovery
  • Backup Strategy
  • Recovery Procedures
• Compliance Considerations
  • GDPR Compliance
  • SOC 2 Readiness
• Technology Stack Summary
• Questions?

---

🎯 High-Level Architecture

System Components

1. Frontend: React + TypeScript (Vite)

• Single-page application (SPA)
• Responsive UI with TailwindCSS
• JWT-based authentication
• Real-time server-sent events (SSE) for chat streaming

2. Backend: Spring Boot (Java 21) + WebFlux

• Reactive, non-blocking REST API
• Stateless architecture (horizontal scaling)
• Spring AI integration for LLM orchestration
• MongoDB reactive drivers

3. Database: MongoDB

• NoSQL document store
• Collections:
  • users - User accounts with bcrypt-hashed passwords
  • groups - Access control groups
  • user_group_links - User-to-group associations
  • swagger_documents - OpenAPI/Swagger specifications
  • postman_collection_documents - Postman collections
  • unified_api_specs - Normalized API definitions
  • api_group_links - API-to-group visibility control
  • conversations - Chat history with step-by-step reasoning
  • audit_logs - Security and compliance logs (TTL-indexed)

4. External Services

• OpenAI API (or Azure OpenAI): LLM for natural language processing
• SMTP Server: Email notifications (activation, password reset)

---

🏛️ System Architecture

Layered Architecture Diagram

┌──────────────────────────────────────────────────────────────────┐
│                        CLIENT TIER                               │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  React 18 SPA (TypeScript + Vite)                          │  │
│  │  - Chat Interface                                          │  │
│  │  - API Configuration UI                                    │  │
│  │  - Admin Dashboard                                         │  │
│  │  - Diagnostics Panel                                       │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                             ↓ HTTPS
┌──────────────────────────────────────────────────────────────────┐
│                     REVERSE PROXY TIER                           │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Nginx / Traefik / Cloud Load Balancer                     │  │
│  │  - SSL/TLS Termination                                     │  │
│  │  - Request routing                                         │  │
│  │  - Rate limiting (optional)                                │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                             ↓ HTTP
┌──────────────────────────────────────────────────────────────────┐
│                     APPLICATION TIER                             │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Spring Boot WebFlux Application (Java 21)                 │  │
│  │                                                            │  │
│  │  ┌──────────────────────────────────────────────────────┐  │  │
│  │  │  Controller Layer                                    │  │  │
│  │  │  - REST API Endpoints                                │  │  │
│  │  │  - SSE Streaming Endpoints                           │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  │                         ↓                                  │  │
│  │  ┌──────────────────────────────────────────────────────┐  │  │
│  │  │  Security Layer                                      │  │  │
│  │  │  - JWT Authentication Filter                         │  │  │
│  │  │  - Role-Based Authorization                          │  │  │
│  │  │  - Group-Based Access Control                        │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  │                         ↓                                  │  │
│  │  ┌──────────────────────────────────────────────────────┐  │  │
│  │  │  Service Layer                                       │  │  │
│  │  │  - AI Agent Service (ReAct Pattern)                  │  │  │
│  │  │  - API Management Service                            │  │  │
│  │  │  - User Management Service                           │  │  │
│  │  │  - Conversation Service                              │  │  │
│  │  │  - Audit Service                                     │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  │                         ↓                                  │  │
│  │  ┌──────────────────────────────────────────────────────┐  │  │
│  │  │  Repository Layer (Reactive)                         │  │  │
│  │  │  - Spring Data MongoDB Reactive                      │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                        ↓ MongoDB Protocol
┌──────────────────────────────────────────────────────────────────┐
│                      DATA TIER                                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  MongoDB 7 Replica Set                                     │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │  │
│  │  │   Primary   │  │  Secondary  │  │  Secondary  │         │  │
│  │  │    Node     │←→│    Node     │←→│    Node     │         │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘         │  │
│  │                                                            │  │
│  │  Collections:                                              │  │
│  │  - users                   - conversations                 │  │
│  │  - groups                  - audit_logs                    │  │
│  │  - user_group_links        - swagger_documents             │  │
│  │  - api_group_links         - postman_collection_documents  │  │
│  │  - unified_api_specs                                       │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│                    EXTERNAL SERVICES                             │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  OpenAI API (api.openai.com)                               │  │
│  │  - GPT-4 for natural language processing                   │  │
│  │  - Function calling for API selection                      │  │
│  └────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  SMTP Server (Configurable)                                │  │
│  │  - Email notifications                                     │  │
│  │  - Account activation                                      │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

Architecture Highlights

• ✅ Reactive, Non-Blocking I/O: Spring WebFlux enables high concurrency with minimal threads
• ✅ Stateless Backend: JWT tokens eliminate need for session storage, enabling horizontal scaling
• ✅ AI Agent with ReAct Pattern: Reasoning + Acting loop for intelligent API selection
• ✅ MongoDB Flexibility: Schema-less design supports evolving data models
• ✅ Event-Driven Communication: Server-Sent Events (SSE) for real-time streaming
• ✅ Security at Every Layer: JWT authentication, RBAC, group-based visibility
• ✅ Docker-First Deployment: Multi-stage builds optimize image size and security

Technical Details

Frontend Stack:

React App (Vite)
├── Authentication Layer (JWT tokens)
├── Routing (React Router)
├── State Management (React Context + hooks)
├── API Client (Axios with interceptors)
├── Real-time Communication (EventSource for SSE)
└── UI Components (TailwindCSS + custom components)

Frontend Implementation Details:

• JWT stored in memory (access token) and HTTP-only cookies (refresh token)
• Automatic token refresh on 401 responses
• Role-based UI rendering (SUPERADMIN, IT, BUSINESS)
• Server-sent events for streaming AI responses

Backend Stack:

Spring Boot WebFlux Application
├── Security Layer (JWT Authentication Filter)
├── Controllers (REST endpoints)
├── Services (Business logic)
│   ├── ChatService (AI conversation orchestration)
│   ├── UserService (User management)
│   ├── ApiService (API specification management)
│   ├── AuditService (Compliance logging)
│   └── ToolServices (AI agent tools)
├── Repositories (Reactive MongoDB access)
├── Spring AI Integration
│   ├── ChatClient (OpenAI integration)
│   ├── Tool Registration (Function calling)
│   └── ReAct Loop Orchestration
└── Security
    ├── JWT Service (Token generation/validation)
    ├── Password Encoder (BCrypt)
    └── RBAC (Role-based access control)

Key Design Patterns:

• Reactive Programming: Non-blocking I/O with Project Reactor (Mono/Flux)
• Stateless Design: No server-side sessions, JWT-based authentication
• Repository Pattern: Data access abstraction
• Service Layer Pattern: Business logic encapsulation

---

🔄 Data Flow Architecture

User Registration & Activation Flow

1. SUPERADMIN creates user (POST /api/admin/users)
   → Backend generates secure activation token (32 bytes)
   → Stored in MongoDB with 48-hour expiration
   → Email sent via SMTP with activation link

2. User clicks activation link (GET /api/auth/validate-token?token=...)
   → Backend validates token expiration and uniqueness
   → Frontend renders password setup form

3. User sets password (POST /api/auth/activate-account)
   → Password hashed with BCrypt (default strength)
   → User marked as active
   → Token invalidated (single-use)
   → Email confirmation sent

Authentication Flow

1. User submits credentials (POST /api/auth/login)
   → Backend validates username/password with BCrypt
   → Generates JWT access token (15 min expiration)
   → Generates JWT refresh token (7 days expiration)
   → Returns both tokens to client
   → Logs login in audit_logs collection

2. Frontend stores tokens:
   → Access token: Memory (JavaScript variable)
   → Refresh token: HTTP-only cookie (secure, SameSite)

3. Authenticated requests:
   → Frontend includes: Authorization: Bearer <access_token>
   → Backend JWT filter extracts username from token
   → Loads user from MongoDB
   → Validates token signature and expiration
   → Sets ReactiveSecurityContext for request

4. Token refresh (when access token expires):
   → Frontend detects 401 response
   → Calls POST /api/auth/refresh with refresh token
   → Backend validates refresh token
   → Issues new access + refresh tokens
   → Frontend updates stored tokens
   → Retries original request

AI Chat Conversation Flow

1. User sends query (POST /api/chat)
   → Request includes:
     - query: Natural language question
     - conversationId: Session identifier
     - maxIterations: ReAct loop limit (default: 5)
   
2. Backend initiates ReAct loop:
   
   a) Backend prepares LLM context:
      → Loads user's accessible APIs from MongoDB
      → Filters by group membership and read-only permissions
      → Converts API metadata to tool definitions
      → Initializes conversation with system prompt, user query, and available tools

   **Iteration 1: List Available APIs**
   b) LLM reasoning:
      → 💭 Thought: "I need to discover what APIs the user has access to"
      → 🎬 Action: list_apis()
   
   c) Backend executes tool:
      → ApiDiscoveryTools.listApis() queries MongoDB
      → Returns: [{"name": "Users API", "description": "..."}, {"name": "Products API", "description": "..."}]
   
   d) Observation sent back to LLM
   
   **Iteration 2: List Endpoints for Selected API**
   e) LLM reasoning:
      → 💭 Thought: "The query relates to users, so I'll explore the Users API endpoints"
      → 🎬 Action: list_endpoints(apiName="Users API")
   
   f) Backend executes tool:
      → ApiDiscoveryTools.listEndpoints() parses OpenAPI/Postman collection
      → Returns: [
           {"method": "GET", "path": "/users", "summary": "List all users"},
           {"method": "POST", "path": "/users", "summary": "Create user"},
           {"method": "GET", "path": "/users/{id}", "summary": "Get user by ID"}
         ]
   
   g) Observation sent back to LLM
   
   **Iteration 3: Endpoint Inspection**
   f) LLM analyzes APIs and decides next action:
      → Example: inspect_endpoint(apiName="Users API", method="GET", path="/users")
   
   g) Backend executes tool:
      → ApiDiscoveryTools.inspectEndpoint() loads OpenAPI schema
      → Returns: Parameters, request body schema, response schema
   
   h) Result sent back to LLM
   
   **Iteration 4: API Execution**
   i) LLM validates parameters and calls API:
      → Example: call_api(apiName="Users API", method="GET", path="/users", params={...})
   
   j) Backend executes tool:
      → ApiInvocationTools.callApi() loads authentication config
      → Constructs HTTP request with:
         - Base URL from configuration
         - Authentication headers (Bearer token, API key, etc.)
         - Query parameters
         - Request body (if applicable)
      → Sends request via WebClient (reactive HTTP client)
      → Applies timeout (default: 30s) and retry logic (default: 3 attempts)
      → Returns API response
   
   k) Result sent back to LLM
   
   **Iteration 5: Data Processing (if needed)**
   l) If user requested filtering/transformation:
      → LLM calls: process_data(data=<api_result>, operation="filter", filter={...})
      → DataTools.processData() applies JSON transformations
      → Returns processed data
   
   **Iteration 6: Final Answer**
   m) LLM formats final response for user
      → No more tool calls (loop terminates)
      → Backend detects completion
   
3. Backend saves conversation to MongoDB:
   → Document includes:
     - User query
     - Final answer
     - Step-by-step reasoning (all thoughts, actions, observations)
     - Execution time
     - Status (SUCCESS, ERROR_PROCESSING)
     - Timestamp

4. Frontend displays response with reasoning steps:
   → 💭 Thought: "I need to list available APIs"
   → 🎬 Action: list_apis()
   → 👁️ Observation: [Users API, Products API]
   → 💭 Thought: "I'll inspect the Users API GET /users endpoint"
   → ...

---

🤖 AI Agent Architecture

ReAct Pattern Implementation

The AI agent follows the ReAct (Reason + Act) pattern for transparent, step-by-step problem solving:

Loop (max iterations: 5):
  1. Reason: LLM analyzes current state and decides next action
  2. Act: Backend executes tool (if requested)
  3. Observe: LLM receives tool result
  4. Repeat until final answer is generated or max iterations reached

Key Implementation Details:

• One tool per iteration: Prevents runaway loops
• Forced tool execution: If LLM hallucinates a tool call in text without emitting actual function call, backend nudges LLM to properly execute the tool
• State management: ReActContext tracks all thoughts, actions, observations
• Timeout protection: Entire chat request has configurable timeout (default: none, but can be set per request)

Available Tools

Memory Management

Conversation History:

• Stored in MongoDB conversations collection
• Retrieved on subsequent messages in same conversation
• Includes:
  • User messages
  • Assistant responses
  • Tool calls and results
  • Step-by-step reasoning

Context Window Management:

• Spring AI automatically manages token limits
• Older messages truncated if context exceeds model limits
• Important system prompts always included

---

🔐 Security Architecture

Authentication & Authorization Flow

Request → JWT Filter → Token Validation → User Loading → RBAC Check → Controller

JWT Authentication Filter (JwtAuthenticationWebFilter):

1. Extracts Authorization: Bearer <token> header
2. Validates token signature with secret key (HMAC-SHA256)
3. Checks token expiration
4. Loads user from MongoDB
5. Sets ReactiveSecurityContext for downstream handlers

Role-Based Access Control (RBAC):

Group-Based API Visibility

Data Model:

users ←→ user_group_links ←→ groups ←→ api_group_links ←→ unified_api_specs

Access Control Logic:

1. User belongs to groups (via user_group_links)
2. APIs are assigned to groups (via api_group_links)
3. User can only chat with APIs in their groups
4. Public APIs: APIs with zero api_group_links are visible to all users
5. SUPERADMIN: Bypasses group restrictions (sees all APIs)

Query Example:

// Find accessible APIs for user "alice@company.com"
1. Find user's groups: [financeGroup, hrGroup]
2. Find APIs in those groups: [PayrollAPI, InvoiceAPI, EmployeeAPI]
3. Find public APIs (no api_group_links): [CalendarAPI]
4. Return union: [PayrollAPI, InvoiceAPI, EmployeeAPI, CalendarAPI]

Password Security

Hashing:

• Algorithm: BCrypt
• Strength: Default (cost factor 10)
• Salting: Automatic (per-password unique salt)

Password Policy:

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character

Reset Flow:

1. User requests reset (POST /api/auth/forgot-password)
2. Backend generates secure token (32 bytes)
3. Token expires in 1 hour
4. User clicks link (GET /api/auth/validate-reset-token?token=...)
5. User sets new password (POST /api/auth/reset-password)
6. Token invalidated (single-use)

API Security (Upstream APIs)

When the AI agent calls external APIs, authentication is configured per API:

Supported Authentication Types:

1. None: Public APIs
2. API Key: Header or query parameter
3. Bearer Token: OAuth2 access token
4. Basic Authentication: Username/password (Base64-encoded)
5. OAuth2 Client Credentials: Automatic token acquisition

Configuration Storage:

• Stored in unified_api_specs.authConfig field
• Encrypted at rest (MongoDB encryption at rest must be enabled at database level)
• Never exposed in API responses

---

⚡ Scalability & Performance

Horizontal Scaling

Backend:

• Stateless Design: No server-side sessions, all state in MongoDB or JWT
• Load Balancer: Distribute requests across multiple backend instances
• Health Checks: /actuator/health endpoint for liveness/readiness probes
• Rolling Updates: Zero-downtime deployments

MongoDB:

• Replica Set: 3+ nodes for high availability
• Automatic Failover: Primary election on failure
• Read Preference: primaryPreferred or secondaryPreferred
• Sharding: (Optional) For very large datasets

Performance Optimizations

Backend:

• Reactive Programming: Non-blocking I/O with Project Reactor
• Connection Pooling: MongoDB connection pool (default: 100 connections)
• Caching: (Not currently implemented, but Spring Cache can be added)

Database:

• Indexes:
  • users.username (unique)
  • unified_api_specs.name (unique)
  • conversations.userId + conversationId (compound)
  • audit_logs.createdAt (TTL index for automatic deletion)

Frontend:

• Code Splitting: Lazy loading of routes
• Tree Shaking: Unused code elimination
• Minification: Vite production build

---

📊 Monitoring & Observability

Health Checks

Endpoint: GET /actuator/health

Response Example:

{
  "status": "UP",
  "groups": [
    "liveness",
    "readiness"
  ],
  "components": {
    "diskSpace": {
      "status": "UP"
    },
    "livenessState": {
      "status": "UP"
    },
    "mail": {
      "status": "UP"
    },
    "mongo": {
      "status": "UP"
    },
    "ping": {
      "status": "UP"
    },
    "readinessState": {
      "status": "UP"
    },
    "ssl": {
      "status": "UP"
    }
  }
}

Metrics

Endpoint: GET /actuator/metrics (requires JWT authentication)

Available Metrics:

• jvm.memory.used / jvm.memory.max
• system.cpu.usage
• http.server.requests (request count, duration, errors)
• mongodb.driver.pool.size (connection pool utilization)

Integration:

• Prometheus (via Spring Boot Actuator)
• Grafana (visualizations)
• Datadog / New Relic (APM)

Logging

Log Levels:

• Production: ERROR level (minimal logging)
• Development: DEBUG level (verbose)

Log Rotation:

• Max file size: 10 MB
• Retention: 30 days
• Total size cap: 1 GB

Log Aggregation:

• ELK Stack (Elasticsearch, Logstash, Kibana)
• Filebeat for log shipping

Audit Logging

Purpose: Compliance and security auditing

Logged Events:

• User logins, logouts, token refreshes
• User CRUD operations
• Group membership changes
• API CRUD operations
• Group-API assignments
• Password changes and resets

Storage:

• MongoDB collection: audit_logs
• TTL index: Automatic deletion after 730 days (configurable)

Structure:

{
  "_id": "...",
  "timestamp": "2026-01-22T14:30:00Z",
  "actorUsername": "admin@example.com",
  "actorUserId": "696ce3767302dd415583cff1",
  "action": "USER_CREATED",
  "entityType": "USER",
  "entityId": "new-user-id",
  "entityName": "newuser@example.com",
  "details": "User created with roles: BUSINESS",
  "ipAddress": "192.168.1.100",
  "userAgent": "Mozilla/5.0...",
  "result": "SUCCESS"
}

---

🚀 Deployment Architecture

Recommended Production Deployment

                     Internet
                        |
                    [Firewall]
                        |
                 [Load Balancer]
                   (HTTPS: 443)
                        |
         ┌──────────────┼──────────────┐
         |              |              |
    [Backend 1]    [Backend 2]    [Backend 3]
    (Port 8080)    (Port 8080)    (Port 8080)
         |              |              |
         └──────────────┼──────────────┘
                        |
                  [MongoDB Replica Set]
                  (Primary + 2 Secondaries)
                        |
                  [Backup Storage]

Components:

• Load Balancer: nginx, HAProxy, or cloud load balancer
• Backend Instances: Docker containers or JVM processes
• MongoDB: Self-hosted or MongoDB Atlas
• SMTP: Internal mail server or SendGrid/AWS SES

High Availability Setup

Backend:

• Minimum 2 instances
• Health check interval: 30 seconds
• Unhealthy threshold: 2 consecutive failures
• Auto-restart on failure

MongoDB:

• Replica Set with 3+ nodes
• Automatic primary election
• Read preference: primaryPreferred

Load Balancer:

• Health check: GET /actuator/health
• Sticky sessions: Not required (stateless)

---

🌐 Network Security

Private Network Deployment

Zero Inbound Access:

• Backend, frontend, MongoDB communicate within private subnet
• VPN or intranet access only
• No public internet exposure

Firewall Rules:

Allow: VPN/Intranet → Load Balancer (80, 443)
Allow: Load Balancer → Backend (8080)
Allow: Backend → MongoDB (27017)
Allow: Backend → OpenAI API (443) [or Azure OpenAI within VNET]
Allow: Backend → SMTP (587)
Deny: All other traffic

Azure OpenAI Option (No Internet Egress)

For maximum security (Banking, Healthcare, Government):

• Deploy Azure OpenAI Service in your Azure VNET
• Use Azure Private Link for connectivity
• No public internet access required
• Data remains within your network boundaries

---

🔄 Disaster Recovery

Backup Strategy

MongoDB:

• Automated daily backups (MongoDB Atlas or mongodump)
• Point-in-time recovery (Atlas)
• Retention: 30 days

Environment Variables:

• Backup .env file after each change
• Store encrypted in secure location

Recovery Procedures

RTO (Recovery Time Objective): ~15-30 minutes RPO (Recovery Point Objective): 24 hours (daily backups)

Steps:

1. Provision new infrastructure
2. Restore MongoDB from backup
3. Deploy application containers
4. Restore .env file
5. Verify health check

---

✅ Compliance Considerations

GDPR Compliance

• Data Sovereignty: All data in your infrastructure
• Right to Erasure: Delete user data via admin interface
• Data Portability: Export conversation history
• Audit Trail: Comprehensive logging

SOC 2 Readiness

• Access Controls: RBAC with group-based visibility
• Audit Logging: 2-year retention (configurable)
• Encryption: TLS in transit, MongoDB encryption at rest
• Monitoring: Health checks, metrics, log aggregation

---

🛠️ Technology Stack Summary

---

📧 Questions?

For architecture-related questions or deployment support:

• Email: support@alesqui.com
• Related Documentation:
  • Configuration Guide - Detailed setup and environment configuration
  • Enterprise Readiness - Security, compliance, and production deployment
  • Trial Quickstart - Quick setup for evaluation
  • Distribution Repository - Docker deployment guides

---

This architecture is designed for security-conscious organizations requiring full control over their data and infrastructure.