Architecture Overview

This section provides a deep-dive into AuroraSOC's architecture for developers contributing to or extending the platform. Understanding the architecture is essential before modifying any component.

High-Level Architecture

Project Structure

AuroraSOC/
├── aurorasoc/              # Python backend (main application)
│   ├── agents/             # 16 AI agents + factory + prompts
│   ├── api/                # FastAPI application (3087 lines)
│   ├── config/             # Pydantic settings (10 subsystem configs)
│   ├── core/               # Auth, DB, logging, rate limiting, tracing
│   ├── engine/             # SOAR playbook engine
│   ├── events/             # Redis Streams, NATS, MQTT consumers
│   ├── memory/             # Three-tier agent memory system
│   ├── models/             # Pydantic domain models + enums
│   ├── services/           # Background scheduler
│   ├── tools/              # 31 MCP tools across 10 modules
│   └── workflows/          # BeeAI AgentWorkflows
├── rust_core/              # Rust core engine
│   ├── src/                # Event normalizer, attestation, publishers
│   └── proto/              # Protobuf definitions
├── dashboard/              # Next.js 15 frontend
│   └── src/                # React components, Zustand store, API client
├── firmware/               # Three firmware platforms
│   ├── esp32s3/            # Zephyr RTOS (C)
│   ├── nrf52840/           # Embassy-rs (Rust)
│   └── stm32/             # Ada SPARK (Ada)
├── infrastructure/         # Docker, monitoring, broker configs
├── tests/                  # pytest test suite
├── alembic/                # Database migrations
└── docs/                   # This Docusaurus documentation

Component Interactions

Request Flow: Alert Investigation

Design Principles

1. Graceful Degradation

Every external dependency has a fallback:

• PostgreSQL down → API serves in-memory demo data
• Redis down → Rate limiter uses in-memory sliding window
• Qdrant down → Agent memory falls back to sliding window only
• Agent offline → Circuit breaker prevents cascading failures

2. Configuration over Code

All behavior is configurable via environment variables with sensible defaults. No code changes needed for:

• LLM provider switching
• Port assignments
• Connection strings
• Feature toggles
• Rate limits

3. Separation of Concerns

Each module has a single responsibility:

• agents/ — AI agent creation and configuration
• tools/ — External system integration
• events/ — Message transport
• memory/ — Knowledge persistence
• engine/ — Playbook execution
• core/ — Cross-cutting concerns (auth, logging, tracing)

4. Event Sourcing Lite

While not a full event-sourced system, AuroraSOC captures all state changes in Redis Streams, providing:

• Complete audit trail
• Event replay capability
• Decoupled producers and consumers

Technology Stack Decision Matrix

Component	Technology	Why This Choice	Alternatives Considered
AI Framework	BeeAI	A2A + MCP native support	LangChain, CrewAI, AutoGen
API	FastAPI	Async, type-safe, OpenAPI	Django, Flask, Express
ORM	SQLAlchemy 2.0	Async, mature, type-safe	Tortoise ORM, Prisma
Event Bus	Redis Streams	Low latency, consumer groups	Kafka, RabbitMQ
Federation	NATS JetStream	Lightweight, persistent	Kafka, Pulsar
IoT Transport	MQTT v5	Industry standard, QoS	AMQP, CoAP
Vector DB	Qdrant	Semantic search, Rust-fast	Pinecone, Weaviate, Milvus
Core Engine	Rust (tokio+axum)	Performance-critical path	Go, C++
Frontend	Next.js 15	SSR, React, Turbopack	Nuxt, SvelteKit
Firmware	C/Rust/Ada	Platform-specific strengths	MicroPython, Arduino
Database	PostgreSQL 16	JSONB, reliability, extensions	MySQL, MongoDB
Tracing	OpenTelemetry	Vendor-neutral, standard	Jaeger, Zipkin (OTLP exports to these)

Port Map

Port	Service	Protocol
8000	FastAPI	HTTP/WS
8080	Rust Core Engine	HTTP
3000	Next.js Dashboard	HTTP
5432	PostgreSQL	TCP
6379	Redis	TCP
6333	Qdrant	HTTP
4222	NATS	TCP
1883	MQTT	TCP
4317	OTLP gRPC	gRPC
9000-9015	A2A Agents	HTTP
9090	Prometheus	HTTP
3001	Grafana	HTTP