# armour007/aura architecture

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

- Interactive diagram: https://gitdiagram.com/armour007/aura
- Repository: https://github.com/armour007/aura

## Overview

##### Project Type and Purpose
- This is a full-stack SaaS/platform called “AURA” that provides a trust protocol for autonomous systems.
- Backend: Go + Gin API server, verification engine, JWT auth, PostgreSQL.
- Frontend: SvelteKit + Tailwind dashboard for managing agents, rules, API keys, logs.
- Supporting infra: migrations, Docker Compose, Kubernetes manifests, Helm charts, observability (Prometheus, Grafana, Tempo), SDKs in Node/Python/Go.

##### File Structure Analysis
- Top-level:
- backend/ – Go server code, cmd entrypoints (migrate, server), migrations, internal packages (api, engine, utils), static OpenAPI spec.
- frontend/ – SvelteKit app (routes, components, lib), build config (Vite, Tailwind), Dockerfile.
- deploy/ – Docker Compose files, Helm chart, Kubernetes manifests, Grafana and OTEL collector configurations.
- sdks/ – codegen scripts and officially supported client libraries in Go, Node, Python.
- scripts/ – automation for smoke tests and quickstart.
- Patterns: monolithic API server (single binary), MVC-style API handlers, SQL migrations folder, microservice-style deployables (backend/frontend separately containerized), multi-environment infra config.

##### Key README Insights
- One HTTP API with versioning, idempotency, and authentication via JWT and hashed API keys.
- Verification engine applies rules (allow/deny, time windows) under /v1/verify.
- Observability baked in: /metrics (Prometheus), tracing (OpenTelemetry + Tempo), Grafana dashboards.
- CI/CD: GitHub Actions workflows for backend/frontend; Docker images published to GHCR; Kubernetes deployment via Helm.

a. Main Components
- Frontend (SvelteKit app)
- API Gateway / Ingress
- Backend API server (Go binary)
- PostgreSQL database
- Redis (optional for rate limiting/idempotency cache)
- OpenTelemetry Collector → Tempo (traces)
- Prometheus → Grafana (metrics/dashboards)
- SDK clients (Go, Node, Python) and external consumer systems (webhooks)
- CI/CD pipelines (GitHub Actions)
b. Relationships and Interactions
- User’s browser ←→ Frontend UI → API calls to Ingress → Backend
- Backend reads/writes to Postgres (migrations, audit logs, API keys, rules).
- Backend optionally reads/writes to Redis for rate limiting/idempotency.
- Backend emits metrics to Prometheus and spans to OTEL collector.
- Grafana dashboards query Prometheus/Tempo.
- SDK clients call /v1/verify on Backend.
- CI/CD pushes container images, deploys Helm chart to Kubernetes cluster.
c. Architectural Patterns & Principles
- Separation of concerns: UI vs API vs data store.
- 12-factor app (config via env vars, containerized services).
- Observability by design (metrics + tracing).
- Infrastructure as code (Helm + k8s manifests).
d. Key Technologies
- Go + Gin, PostgreSQL, SvelteKit, Tailwind CSS
- Docker / Docker Compose, Kubernetes, Helm
- OpenTelemetry, Prometheus, Grafana, Tempo
- GitHub Actions for CI/CD
- SDKs: Node, Python, Go

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser & SDK Consumers
    subgraph "Browser & SDK Consumers"
        direction TB
        Browser["User Browser"]:::frontend
        Frontend["Frontend (SvelteKit)"]:::frontend
        SDK["SDK Clients (Go/Node/Python)"]:::sdk
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CI["GitHub Actions"]:::cicd
        CR["Container Registry (GHCR)"]:::cicd
    end

    %% Infrastructure as Code
    subgraph "Infrastructure as Code"
        direction TB
        DC["Docker Compose Configs"]:::infra
        K8S["Kubernetes Manifests"]:::infra
        HELM["Helm Charts"]:::infra
        GFDASH["Grafana Dashboards & Provisioning"]:::obs
        PROMCFG["Prometheus Config & Alerts"]:::obs
        TEMPCFG["Tempo Tracing Config"]:::obs
        OTELCFG["OTEL Collector Config"]:::obs
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        direction TB
        LB["Ingress / API Gateway"]:::infra
        subgraph "Backend Service"
            direction TB
            BE["Backend API Server"]:::api
            subgraph "Backend Codebase"
                direction TB
                MIGR["DB Migrations"]:::data
                MIGCLI["Migration CLI"]:::api
                ENGINE["Verification Engine"]:::api
                APIHAND["API Handlers"]:::api
                JWT["JWT Auth Utility"]:::api
                PASS["Password Hashing Utility"]:::api
                WEBHOOK["Webhook Utility"]:::api
                OPENAPI["OpenAPI Spec"]:::api
            end
        end
        POST["PostgreSQL"]:::data
        REDIS["Redis (Cache)"]:::data
        OTEL["OTEL Collector"]:::obs
        PROM["Prometheus"]:::obs
        GRAF["Grafana"]:::obs
        TEMPO["Tempo"]:::obs
    end

    %% Connections
    Browser -->|"HTTPS"| Frontend
    Frontend -->|"HTTPS"| LB
    SDK -->|"HTTPS"| LB
    LB -->|"HTTP"| BE
    BE -->|"SQL"| POST
    BE -->|"Cache"| REDIS
    BE -->|"metrics"| PROM
    BE -->|"traces"| OTEL
    PROM -->|"query"| GRAF
    OTEL -->|"trace export"| TEMPO
    CI -->|"build/deploy"| CR
    CR -->|"deploy images"| LB
    CI -->|"deploy IaC"| K8S
    CI -->|"deploy IaC"| HELM
    CI -->|"deploy IaC"| DC

    %% Click Events
    click Frontend "https://github.com/armour007/aura/tree/main/frontend/"
    click BE "https://github.com/armour007/aura/blob/main/backend/cmd/server/main.go"
    click MIGR "https://github.com/armour007/aura/tree/main/backend/db/migrations/"
    click MIGCLI "https://github.com/armour007/aura/blob/main/backend/cmd/migrate/main.go"
    click ENGINE "https://github.com/armour007/aura/blob/main/backend/internal/engine/engine.go"
    click APIHAND "https://github.com/armour007/aura/tree/main/backend/internal/api/"
    click JWT "https://github.com/armour007/aura/blob/main/backend/internal/utils/jwt.go"
    click PASS "https://github.com/armour007/aura/blob/main/backend/internal/utils/password.go"
    click WEBHOOK "https://github.com/armour007/aura/blob/main/backend/internal/utils/webhook.go"
    click OPENAPI "https://github.com/armour007/aura/blob/main/backend/static/openapi.json"
    click DC "https://github.com/armour007/aura/blob/main/docker-compose.yml"
    click K8S "https://github.com/armour007/aura/tree/main/deploy/k8s/"
    click HELM "https://github.com/armour007/aura/tree/main/deploy/helm/aura/"
    click GFDASH "https://github.com/armour007/aura/tree/main/deploy/grafana/"
    click PROMCFG "https://github.com/armour007/aura/tree/main/deploy/prometheus/"
    click TEMPCFG "https://github.com/armour007/aura/tree/main/deploy/tempo/"
    click OTELCFG "https://github.com/armour007/aura/blob/main/deploy/otelcol/config.yaml"
    click CI "https://github.com/armour007/aura/blob/main/.github/workflows/backend.yml"
    click CI "https://github.com/armour007/aura/blob/main/.github/workflows/frontend.yml"
    click SDK "https://github.com/armour007/aura/tree/main/sdks/go/aura/"
    click SDK "https://github.com/armour007/aura/tree/main/sdks/node/"
    click SDK "https://github.com/armour007/aura/tree/main/sdks/python/"
    click Scripts "https://github.com/armour007/aura/tree/main/scripts/"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef api fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef data fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef obs fill:#e1bee7,stroke:#4a148c,color:#4a148c;
    classDef cicd fill:#cfd8dc,stroke:#37474f,color:#37474f;
    classDef infra fill:#f0f4c3,stroke:#827717,color:#827717;
    classDef sdk fill:#b2ebf2,stroke:#006064,color:#006064;
    classDef Scripts fill:#f8bbd0,stroke:#880e4f,color:#880e4f;
```
