# siriusscan/sirius architecture

> Architecture diagram of the GitHub repository siriusscan/sirius, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siriusscan/sirius
- Repository: https://github.com/siriusscan/sirius

## Overview

##### Project Type and Purpose
- Sirius Scan is a microservices-based full-stack application for vulnerability scanning.
- It comprises:
- A web frontend (Next.js/React) for user interaction
- A backend API service (Go) exposing REST/trpc endpoints
- A scanning engine (Go) that executes vulnerability scans via community-driven modules (e.g., Nmap, Rustscan)
- Supporting infrastructure: RabbitMQ (AMQP message broker), PostgreSQL (relational database), Redis (key-value store)

##### File Structure Analysis
- Top-level directories:
- sirius-ui      → Next.js frontend, Prisma ORM, tRPC routers, React components
- sirius-api     → Go REST/trpc API, handlers, routes, Dockerfile
- sirius-engine  → Go scanning engine, modular “apps”, AMQP integration, Dockerfile
- rabbitmq       → RabbitMQ config
- docker-compose.yaml → orchestrates all services
- Patterns & Config:
- Docker-based microservices (each folder has a Dockerfile, .env)
- Messaging through RabbitMQ (AMQP) for decoupled scan job dispatch
- Persistence in PostgreSQL and Redis
- trpc in the UI for type-safe API calls

##### README Insights
- Confirms microservices and ports:
- sirius-ui      : 3000
- sirius-api     : 9001
- sirius-engine  : 5174
- rabbitmq       : 5672/15672
- postgres       : 5432
- redis (valkey) : 6379
- Describes user flows: login, scan launch, vulnerability browsing, host/inventory view, terminal access

a. Main Components
- User’s Browser (UI)
- Frontend Service (sirius-ui)
- API Service (sirius-api)
- Scan Engine (sirius-engine)
- Message Broker (RabbitMQ)
- Database (PostgreSQL)
- Cache/Key-Value Store (Redis)
- External Scan Modules (e.g., Nmap, Rustscan)

b. Relationships & Interactions
1. Browser → HTTP/HTTPS → Next.js UI
2. UI → tRPC/REST → Go API (sirius-api)
3. API ↔ PostgreSQL (read/write scan definitions, user data)
4. API ↔ Redis (cache session, quick lookups)
5. API → AMQP publish → RabbitMQ “scan.jobs” queue
6. Engine ← AMQP consume ← scan.jobs
7. Engine executes modules (calls Nmap/Rustscan binaries or libraries)
8. Engine → AMQP publish → RabbitMQ “scan.results” queue or calls API endpoint for result ingestion
9. API consumes results, persists them (PostgreSQL), optionally caches to Redis
10. UI subscribes/polls API for real-time updates

c. Architectural Patterns
- Microservices with message-driven eventing (AMQP)
- Layered separation (UI / API / Engine)
- MVC pattern in frontend, handler/route layering in backend
- SDK/shared library (go-api) to interact uniformly with core services

d. Key Technologies
- Frontend: Next.js, React, tRPC, Prisma, Tailwind CSS
- Backend API: Go, Gorilla Mux or native HTTP, Docker
- Scanner Engine: Go, modular “apps” pattern, custom scripts, AMQP client
- Messaging: RabbitMQ (AMQP)
- Persistence: PostgreSQL, Redis
- Deployment: Docker Compose

##### Essential Details to Capture
- All microservices and their ports
- Data flow paths (job submission vs. result ingestion)
- External module invocation within the engine
- Caching and persistence flows
- Deployment artifact boundaries (Docker Compose groups)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        Browser["User Browser"]:::external
        UI["sirius-ui (Next.js)"]:::frontend
    end

    subgraph "Application Layer"
        API["sirius-api (Go REST/trpc)"]:::backend
    end

    subgraph "Processing Layer"
        Engine["sirius-engine (Go Engine)"]:::engine
        ExtMod["External Modules (Nmap, Rustscan)"]:::engine
    end

    subgraph "Infrastructure"
        Rabbit["RabbitMQ (AMQP)"]:::infra
        Postgres["PostgreSQL"]:::infra
        Redis["Redis"]:::infra
        Compose["Docker Compose"]:::infra
    end

    Browser -->|"HTTP/HTTPS:3000"| UI
    UI -->|"tRPC/REST:9001"| API
    API -->|"SQL:5432"| Postgres
    API -->|"Redis:6379"| Redis
    API -->|"AMQP publish scan.jobs"| Rabbit
    Rabbit -->|"AMQP consume scan.jobs"| Engine
    Engine -->|"exec modules"| ExtMod
    Engine -->|"AMQP publish scan.results"| Rabbit
    Rabbit -->|"AMQP deliver scan.results"| API
    API -->|"store results"| Postgres
    API -->|"cache results"| Redis
    UI -->|"poll/subscribe"| API

    click UI "https://github.com/siriusscan/sirius/tree/main/sirius-ui/"
    click API "https://github.com/siriusscan/sirius/tree/main/sirius-api/"
    click Engine "https://github.com/siriusscan/sirius/tree/main/sirius-engine/"
    click Rabbit "https://github.com/siriusscan/sirius/blob/main/rabbitmq/rabbitmq.conf"
    click Compose "https://github.com/siriusscan/sirius/blob/main/docker-compose.yaml"

    classDef frontend fill:#007BFF,stroke:#333,color:#fff
    classDef backend fill:#28A745,stroke:#333,color:#fff
    classDef engine fill:#FD7E14,stroke:#333,color:#fff
    classDef infra fill:#6C757D,stroke:#333,color:#fff
    classDef external fill:#17A2B8,stroke:#333,color:#fff
```
