Skip to main content

AuroraSOC Developer Guide

This is the main developer entry point for AuroraSOC.

Use this page to understand the platform quickly, choose the right deep-dive documents, and build safely without guessing.

Who This Guide Is For​

  • Backend engineers extending API, agents, tools, and workflows
  • Platform engineers operating infrastructure and observability
  • Security engineers integrating SIEM, EDR, SOAR, and CPS data paths
  • AI/ML engineers working on Granite model integration and training

Read This First (Learning Paths)​

Path 1: New to the Codebase (90 minutes)​

  1. Architecture Overview
  2. Source of Truth (Canonical Facts)
  3. Settings System
  4. REST API Endpoints

Outcome:

  • You understand the runtime topology, configuration model, and API entry points.

Path 2: Build Features Safely (half day)​

  1. Agent Factory
  2. Orchestrator Dispatch
  3. Tools Base Class
  4. Testing Strategy
  5. Writing Tests

Outcome:

  • You can add features with predictable behavior and test coverage.

Path 3: Operate in Production-Like Environments​

  1. Docker Configuration
  2. Monitoring
  3. Database Migrations
  4. CI/CD Pipeline

Outcome:

  • You can deploy, observe, and troubleshoot runtime systems confidently.

Architecture in One Screen​

Canonical Facts You Should Not Guess​

  • Agent topology: 1 orchestrator + 16 specialists
  • A2A ports: 9000 to 9016
  • Python requirement: >=3.12
  • Dashboard Node recommendation: 22
  • Docs Node support: >=18

Authoritative references:

Daily Developer Workflow​

# 1) Install dependencies
make install

# 2) Start infra dependencies
make docker-up

# 3) Run migrations
make migrate

# 4) Start API
make api

# 5) Start dashboard (new terminal)
make dashboard-dev

Before pushing code:

make lint
make type-check
make test

Where Things Live in the Repository​

  • aurorasoc/agents/ agent construction, prompts, orchestration
  • aurorasoc/api/ HTTP and WebSocket interfaces
  • aurorasoc/tools/ MCP tool modules and integrations
  • aurorasoc/events/ Redis, NATS, and MQTT event handling
  • aurorasoc/memory/ tiered memory implementation
  • aurorasoc/config/ settings and environment mapping
  • rust_core/ normalization and attestation runtime
  • dashboard/ frontend and API client
  • tests/ unit and integration tests

Common Extension Tasks​

Add a new MCP tool​

  1. Implement tool in the relevant module under aurorasoc/tools/
  2. Ensure it derives from the base tool class and follows error contracts
  3. Wire it through tool loading path
  4. Add tests
  5. Update tool docs

Recommended references:

Add or modify an API endpoint​

  1. Implement route and schema updates in API layer
  2. Enforce auth and permission checks
  3. Add tests for success and failure paths
  4. Update docs examples and behavior notes

Recommended references:

Modify agent behavior​

  1. Update prompts, memory policy, or dispatch behavior
  2. Validate handoff behavior and timeout semantics
  3. Confirm observability signals remain intact
  4. Update architecture and behavior docs

Recommended references:

Troubleshooting Strategy​

Use this order when debugging:

  1. Verify configuration and secrets first
  2. Verify dependencies and network reachability
  3. Verify agent and tool health endpoints
  4. Verify event flow and stream lag
  5. Verify logs, traces, and metrics correlation

Recommended references:

Contributing Standards​

Before opening a pull request:

  1. Keep changes scoped and testable
  2. Include tests for behavior changes
  3. Update documentation in the same PR
  4. Ensure docs meet quality standards

References:

Next Step​

If you are new, continue to Architecture Overview.