1. Architecture Overview

The AIQGEN platform uses a distributed microservices architecture, designed for high availability, scalability and compliance with U.S. financial regulations.

1.1 Architecture Diagram

┌───────────────────────────────────────────────────────────────────────────────┐
│                          PRESENTATION LAYER                                   │
│   • Web/Mobile Apps • Core Banking • CRM • Partner APIs                       │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                  API GATEWAY + POLICY ENGINE (PDP/PEP)                         │
│   • Authentication • Rate Limiting • Routing                                   │
│   • Privacy Consent • Data Masking • Auditing                                 │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────── AI AGENTS ORCHESTRATOR ─────────────────────────┐
│ Coordinates specialized agents and resolves multi-agent workflows            │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────── AI AGENTS LAYER ───────────────────────────────┐
│ • Advisor Agent • Offers Agent • Compliance AI Agent                         │
│ Each agent:                                                                   │
│   ┌───────────────┐   ┌──────────────────────┐   ┌──────────────────────┐      │
│   │ Reasoning     │   │ MCP Client + Planner │   │ Knowledge Base (RAG) │      │
│   │ Guardrails    │   │ - Discovers Tools    │   │ - Regulations, docs  │      │
│   │ HITL/Fallback │   │ - Calls via MCP      │   │ - Vector DB          │      │
│   └───────────────┘   └──────────────────────┘   └──────────────────────┘      │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────── MCP LAYER (TOOLING HUB) ──────────────────────────┐
│ MCP Router/Hub                                                                 │
│  • AuthZ/Scopes • Versioning • Circuit Breakers • Quotas                       │
│  • Logging/Tracing • Metrics                                                   │
│                                                                                │
│ Exposed tools (from Core or external):                                         │
│   - MarketData Tool (quotes, FX)                                               │
│   - Trading Tool (orders)                                                      │
│   - KYC/AML Tool                                                               │
│   - Compliance Tool ◄── via Core                                               │
│   - Rules Tool ◄── via Core                                                    │
│   - Risk Model Tool ◄── via Core                                               │
│   - RAG/VectorDB Tool (documents/regulations)                                  │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────── DATA & INTEGRATIONS LAYER ─────────────────────┐
│ • PostgreSQL (clients, transactions)                                          │
│ • Redis (cache) • S3/Blob (documents)                                         │
│ • Financial APIs • SEC • Credit Bureaus                                       │
│ • Feature Store • Event Bus (Kafka) • KMS/Secret Manager                      │
│ • Consent/Data Governance Layer (Privacy compliance, consent store)           │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────── CORE SERVICES LAYER ───────────────────────────┐
│ Main services (sources of truth):                                             │
│   • Compliance Engine (Suitability, SEC regulations)                          │
│   • Rules Engine (customizable policies)                                      │
│   • Risk/ML Engine (online inference)                                         │
│                                                                               │
│ Direct platform services:                                                     │
│   • ML/AI Engine (training, batch scoring)                                    │
│   • Analytics Engine (dashboards, reports, BI)                                │
│   • Model Registry / MRM (model management, drift, fairness, auditing)        │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                          OUTPUT TO CLIENT                                     │
│   • Structured JSON, insights, recommendations, alerts or validations         │
│   • Explainability + Evidence + Regulation/Policy IDs                         │
└───────────────────────────────────────────────────────────────────────────────┘

1.2 Main Components

API Gateway + Policy Engine

Single entry point with OAuth 2.0 authentication, rate limiting, privacy validation and complete auditing.

AI Agents Orchestrator

Coordinates specialized agents, manages multi-agent workflows and optimizes performance.

Specialized AI Agents

Each agent has three components:

Reasoning Engine: Decision logic, guardrails and human escalation
MCP Client: Discovery and invocation of external tools
Knowledge Base: Knowledge base with regulations and documents

MCP Hub (Tooling Hub)

Centralized hub that exposes tools to agents: market data, compliance, risk, trading, etc.

Data Layer

PostgreSQL (data), Redis (cache), S3 (files), Vector DB (knowledge), Kafka (events).

Core Services

Compliance Engine, Rules Engine, Risk/ML Engine, Analytics Engine and Model Registry.

1.3 MCP Hub - Available Tools

Centralized hub that exposes tools to AI agents via MCP protocol.

Tool	Description	Source
market_data	Real-time quotes, FX, indexes	Market APIs
trading	Order sending, position queries	Core Banking
kyc_aml	Identity verification and AML	Credit Bureaus
compliance	SEC regulations validation	Compliance Engine
rules	Customizable rules execution	Rules Engine
risk_model	Scoring and risk analysis	Risk/ML Engine
rag_vectordb	Documents and regulations search	Vector DB

Features: Automatic discovery, versioning, circuit breakers, quotas, complete observability.

1.4 AI Agents Architecture

Each agent has three components working together:

Reasoning Engine

Decision logic, security guardrails, human escalation and fallback strategies.

MCP Client

Automatic tool discovery, execution planning and result aggregation.

Knowledge Base (RAG)

Vector database with regulations, technical documents, FAQs and semantic search.

Processing Flow

text

1. Receive request → 2. Analyze context → 3. Discover tools
4. Query knowledge → 5. Execute logic → 6. Invoke tools
7. Aggregate results → 8. Apply validations → 9. Return response

1.5 Data Layer & Integrations

Storage

PostgreSQL: Transactional data and client profiles
Redis: Distributed cache and sessions
S3/Blob: Documents and audit files
Vector DB: Embeddings for semantic search

Feature Store & Event Bus

Feature Store: Real-time ML features
Kafka: Asynchronous events and streaming

External Integrations

System	Protocol	Data
Financial APIs	OAuth 2.0	Accounts, transactions, investments
SEC	API Key	Regulations, communications
FINRA	API Key	Regulations, products, suitability
Credit Bureaus	OAuth 2.0	Score, history, inquiries
Market APIs	API Key	Quotes, FX, indexes

Data Governance

Consent Management: Privacy consent management
Data Lineage: Personal data traceability
Data Masking: Anonymization and pseudonymization
KMS/Secret Manager: Secure key management

1.6 Scalability

The platform scales horizontally using AWS Elastic Beanstalk:

Auto-scaling: Instances scale automatically based on CPU (70%), memory (80%) and requests/second (> 500 req/s per instance)

Minimum: 2 instances per agent (high availability)
Maximum: 20 instances per agent (demand peaks)
P99 Latency: < 200ms for 99% of requests
Throughput: > 5,000 requests/second per environment

1.7 Core Services

Platform sources of truth that provide fundamental capabilities:

Main Services

Compliance Engine: SEC suitability, FINRA rules, regulatory monitoring
Rules Engine: Customizable policies, versioning, hot deployment
Risk/ML Engine: Real-time scoring, model serving, A/B testing

Platform Services

ML/AI Engine: Training, batch scoring, model serving, AutoML
Analytics Engine: Dashboards, reports, BI, real-time analytics
Model Registry: Versioning, drift detection, fairness monitoring

2. API Reference

The AIQGEN API exposes specialized AI agents for direct interaction with end users. Production base URL:

Production Base URL: https://api.aiqgen.com/v1

Sandbox Base URL: https://sandbox-api.aiqgen.com/v1

2.1 Investment Advisor Agent

The Advisor Agent is a financial assistant specialized in investment guidance, investor profile analysis and product suitability according to SEC regulations.

2.2 Authentication

The API uses OAuth 2.0 (Client Credentials) and API Keys for authentication.

bash

# OAuth 2.0
curl -X POST https://api.aiqgen.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials",
    "scope": "advisor:read advisor:write"
  }'

# API Key (alternative)
curl https://api.aiqgen.com/v1/agents/advisor/interact \
  -H "X-API-Key: aiq_live_sk_1234567890abcdef" \
  -H "Content-Type: application/json"

2.3 Advisor Agent Endpoints

General Interaction

POST /agents/advisor/interact

Open interaction with financial assistant in natural language

Profile Analysis

POST /agents/advisor/analyze-profile

Structured investor profile analysis and SEC suitability

Customer Summary

GET /agents/advisor/summary/{customerId}

Consolidated customer position and recommendations summary

Example: General Interaction

json

{
  "customerId": "clt_9f8e7d6c5b4a3",
  "query": "What investments are suitable for my profile?",
  "context": {
    "sessionId": "sess_123",
    "timestamp": "2025-09-30T14:23:45.678Z"
  }
}

Example: Profile Analysis

json

{
  "customerId": "clt_9f8e7d6c5b4a3",
  "profile": {
    "age": 35,
    "monthly_income": 15000.00,
    "net_worth": 500000.00,
    "objectives": ["retirement", "emergency_fund"],
    "investment_experience": "intermediate",
    "time_horizon": 240
  }
}

Success Response

json

{
  "status": "success",
  "data": {
    "customerId": "clt_9f8e7d6c5b4a3",
    "response": "Based on your profile, I recommend a diversified portfolio...",
    "recommendations": [
      {
        "product": "Moderate Multi-Strategy Fund",
        "allocation": 40.0,
        "risk": "moderate",
        "justification": "Suitable for your moderate risk profile"
      }
    ],
    "compliance": {
      "suitable": true,
      "regulation": "SEC Rule 2111",
      "documents_required": ["customer_agreement", "suitability_questionnaire"]
    },
    "metadata": {
      "agent": "advisor",
      "timestamp": "2025-09-30T14:23:45.678Z",
      "latency_ms": 187
    }
  }
}

2.4 Error Codes

HTTP Code	Error Code	Description	Recommended Action
400	INVALID_REQUEST	Invalid or missing parameters	Check documentation and correct parameters
401	UNAUTHORIZED	Invalid or expired token	Renew authentication token
403	FORBIDDEN	No permission for this resource	Check token scopes
404	NOT_FOUND	Resource not found	Verify resource ID
429	RATE_LIMIT_EXCEEDED	Request limit exceeded	Wait before retry (see Retry-After header)
500	INTERNAL_ERROR	Internal server error	Try again. If persists, contact support
503	SERVICE_UNAVAILABLE	Service temporarily unavailable	Wait and try again

Error Response Example

json

{
  "status": "error",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Parameter 'monthly_income' is required",
    "details": {
      "field": "monthly_income",
      "constraint": "required",
      "received": null
    },
    "request_id": "req_abc123xyz789",
    "timestamp": "2025-09-30T14:30:00.000Z"
  }
}

Documentation In Development

Sections 3-11 are being finalized. Meanwhile, you can:

Request Beta Access Technical Contact

AIQGEN API Technical Documentation

1. Architecture Overview

1.1 Architecture Diagram

1.2 Main Components

API Gateway + Policy Engine

AI Agents Orchestrator

Specialized AI Agents

MCP Hub (Tooling Hub)

Data Layer

Core Services

1.3 MCP Hub - Available Tools

1.4 AI Agents Architecture

Reasoning Engine

MCP Client

Knowledge Base (RAG)

Processing Flow

1.5 Data Layer & Integrations

Storage

Feature Store & Event Bus

External Integrations

Data Governance

1.6 Scalability

1.7 Core Services

Main Services

Platform Services

2. API Reference

2.1 Investment Advisor Agent

2.2 Authentication

2.3 Advisor Agent Endpoints

General Interaction

Profile Analysis

Customer Summary

Example: General Interaction

Example: Profile Analysis

Success Response

2.4 Error Codes

Error Response Example

Documentation In Development