Architectural Overview

ÆHub (AeSoul Digital Hub) has evolved from a portal-automation tool into a full-stack AI agent orchestration platform. The system combines a Next.js frontend with an asynchronous FastAPI backend built around A.U.R.O.R.A. (Autonomous Uplink & Real-time Operations Robotic Assistant) — a LangGraph-based reasoning loop that treats the LLM as a decision-making component rather than a simple text-generation endpoint.

The platform now models every request as:

reasoning → tool selection → tool execution → observation → next reasoning step → final response

with persistent memory, retrieval-augmented context, multi-agent delegation, and real-time event streaming layered around that loop.

The original Playwright-based academic portal automation is retained as one of several skills exposed to the agent, rather than being the platform's sole purpose.

User
  |
  v
API / Realtime Interface (Next.js + FastAPI)
  |
  v
A.U.R.O.R.A. Agent Runtime (LangGraph)
  |
  v
Reasoning + Tool Selection
  |
  v
Tools / Skills / Subagents
  |
  v
Observations + Memory (PostgreSQL + pgvector)
  |
  v
Next Agent Step -> Final Response

Component Architecture & System Topology

1. Frontend Presentation Layer

Next.js (App Router) + React, TypeScript, Tailwind CSS, Zustand, and Radix-based UI, with Recharts for dashboard visualizations.

It consumes REST, WebSocket, and Server-Sent Events endpoints and renders real-time agent execution events streamed from the backend EventBus.

2. Backend Service Layer

FastAPI backend (backend/main.py) exposing REST endpoints, WebSocket communication, Server-Sent Events, agent orchestration endpoints, and dedicated academic, media, and voice routers.

• Academic Router (routers/academic.py): authentication and data-sync routes backed by the Playwright automation skill.
• Media Router (routers/media.py): file lifecycle management, including upload, processing, and linking media to user profiles.
• Orchestrator (routers/orchestrator.py): exposes POST /api/orchestrator/ask, the main entry point into the A.U.R.O.R.A. agent graph, plus session-level slash commands (/stop, /clear, /precise, /creative, /deep, /fast).

3. Agent Runtime & Skill Registry

The LangGraph-based A.U.R.O.R.A. runtime maintains explicit state — messages, session information, and intent — across an agent → tool-node → agent loop.

Skills implement a shared BaseSkill abstraction and are dynamically discovered from app.skills via get_skill(), then aggregated into the LLM's bound toolset.

Current skills include:

• web search;
• sandboxed Python and shell execution;
• a supervisor skill that delegates to a specialized Research Subagent through a reusable SubagentFactory;
• an MCP bridge with a complete MCPTransportLayer client for external tool integration.

4. Memory & Retrieval Layer

• Working memory: LangGraph in-graph state.
• Conversational memory: LangGraph checkpoints persisted in PostgreSQL via AsyncPostgresSaver.
• Semantic, episodic, and procedural memory assembled by AuroraMemoryManager and injected into the agent's system prompt.
• Dedicated RAG pipeline based on pgvector, including retrieval evaluation and citation-aware responses — previously only planned as a foundation, now implemented as a first-class retrieval skill.

5. Automation Engine & Session Store (Legacy, Retained)

Playwright drives headless browser automation using Chromium, Firefox, or WebKit for portals without native REST APIs, handling dynamic DOM state and multi-step authentication.

Browser context, including cookies and storage, is cached under playwright_session/ to avoid repeated authentication during subsequent runs.

6. Distributed Execution Layer

A Durable Task Runtime built on Celery/Redis handles long-running and background workloads with state recovery, idempotency, and Dead Letter Queue handling for failed jobs.

This replaces the earlier synchronous and in-process execution model.

A proactive scheduler drives recurring and background agent workloads.

7. Security Layer

• PromptInjectionFilter applied to all inbound text.
• Persistent RBAC policy engine instead of session-based placeholders.
• Tool Gateway enforcing per-tool risk metadata (LOW / MEDIUM / HIGH) and approval requirements.
• Production Human-In-The-Loop WorkflowEngine with checkpoint-based approval pauses and resumption.
• Hardened Docker sandbox isolation for code execution using CPU limits, pids-limit, and read-only mounts.

8. Observability Layer

JSON structured and semantic logging, OpenTelemetry distributed tracing, and a Prometheus /metrics exporter.

The platform also includes an internal EventBus with an SSE stream:

GET /api/events

which is consumed by the frontend for live agent logs, notifications, and security events.

Fact vs. Inference Analysis

Core Data & Automation Workflows

Agent Tool-Calling Loop (Primary Workflow)

Skill
  |
  v
Tool registration
  |
  v
Skill Registry
  |
  v
LangGraph
  |
  v
LLM binds available tools
  |
  v
LLM emits tool call
  |
  v
ToolNode executes function
  |
  v
Result returned to LLM -> next step or final answer

Academic Data Synchronization (Legacy Workflow, Retained)

1. Trigger: the client sends POST /api/academic/login.
2. Session verification: the academic router checks playwright_session/ for a valid, non-expired browser context.
3. Execution: if cached, Playwright reuses the existing context; if expired or unavailable, it launches a browser, completes the portal login flow, and writes fresh cookies to playwright_session/.
4. Normalization & storage: parsed data is structured and persisted through database.py.
5. Response: a JSON payload is returned to the Next.js frontend.

Infrastructure, Containerization & Operations

services:
  frontend:
    build: ./frontend
    ports:
      - "2003:3000"
    environment:
      - NEXT_PUBLIC_API_URL=http://backend:3002
  backend:
    build: ./backend
    ports:
      - "3002:8000"
    volumes:
      - ./backend/playwright_session:/app/playwright_session
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/aesoul
      - REDIS_URL=redis://redis:6379/0
  postgres:
    image: postgres
    ports:
      - "5432:5432"
  redis:
    image: redis
    ports:
      - "6379:6379"

Known Open Items

• The repository currently ships lowercase dockerfile files while docker-compose.yaml references Dockerfile; these must be aligned before building on case-sensitive filesystems.
• No LICENSE is currently declared in repository metadata; reuse and redistribution rights should not be assumed until one is added.
• The backend defines an unsafe fallback for AEHUB_SECRET_KEY; production deployments must require a strong secret explicitly and fail closed when it is missing.

Performance, Scalability & Security Posture

The original single-node, in-process bottlenecks — including headless-browser memory pressure and local-disk session caching that blocked horizontal scaling — are now addressed through:

• Distributed task execution: Celery/Redis worker pools with Dead Letter Queue handling, moving long-running automation and agent work outside the request/response cycle.
• Externalized state: PostgreSQL for checkpoints, memory, and structured data, combined with Redis for caching and queues, allowing stateless API replicas to scale horizontally.
• Model-tiered execution: lighter models for deterministic subtasks and stronger models for planning and research, consistent with the platform's cost-optimization goals.
• Tool-level risk enforcement: every tool call passes through the Tool Gateway's risk classification before execution, with high-risk operations such as shell execution requiring explicit approval through the HITL workflow.

Coming Next — M17: Cloud-Only Open-Weight AI Fleet

ÆHub is evolving from a single-provider/model LLM architecture based on Groq into a true cloud-only AI operating platform with multi-provider support and a zero-paid-inference policy (AEHUB_FREE_ONLY=true, AEHUB_ALLOW_PAID_PROVIDERS=false).

Planned Roadmap (Revision v2)

• Cloud Model Router (backend/app/inference/): Groq (PRIMARY, low latency), OpenRouter (PRIMARY, model variety), Cloudflare Workers AI (SECONDARY, diversification), and HuggingFace Inference (EMERGENCY), with automatic provider fallback in case of errors or rate limits.
• Model Freshness Watch: a high-priority scheduled job that periodically validates model slugs against real provider APIs and automatically disables models that are deprecated or removed from the free tier.
• Routing Intelligence (routing/): TaskComplexityClassifier, CapabilityResolver, EscalationPolicy, and FallbackStrategy, providing dynamic capability-based scoring instead of relying on a fixed model slug.
• Free-Only Policy Enforcement (budget/): FreeOnlyPolicyEnforcer, CostGuard, and QuotaReservationSystem, tracking quotas per (provider, model) pair rather than as a single bucket per provider.
• Declarative Model Registry (models/manifests.py): an initial fleet such as openai/gpt-oss-20b / 120b and qwen/qwen3.6-27b on Groq for FAST/GENERAL/CODING, plus current reasoning and long-context models on OpenRouter free tiers. These are treated as defaults rather than permanent truth and are resolved and verified at runtime by the registry.
• Extended Evaluation Suite: golden tasks G01–G16, including G14 (provider unavailable), G15 (model deprecated at runtime), and G16 (quota exhausted).
• Frontend Dashboard Fleet Status: real-time view of provider availability, remaining quota per model, and models automatically deprecated or disabled.
• ADR-018 → ADR-035: documentation of architectural decisions for the fleet, including ADR-035 dedicated to project licensing.
• Preliminary fixes: replacement of the currently used Groq model (llama3-70b-8192, deprecated) with an active model, and removal of the insecure AEHUB_SECRET_KEY fallback.

Release Approach

A vertical MVP will be released first — two providers with static fallback — before introducing full scoring, health monitoring, and lifecycle management.