# auditware/radar architecture

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

- Interactive diagram: https://gitdiagram.com/auditware/radar
- Repository: https://github.com/auditware/radar

## Overview

##### Project Type and Purpose
- This is an open-source static analysis tool (“radar”) for Anchor-based Rust smart contracts.
- It provides a CLI front-end, a controller/orchestrator, a Python/Django REST API with Celery workers, and a Rust-based parser library (rust_syn_wrapper).
- Its goal is to parse a user’s Rust contract code into an AST, apply user-supplied or built-in YAML templates (rules) against that AST via a Python rule engine, and report potential security issues.

##### File-Structure Analysis
Top-level directories and roles:
- /radar (root executable script): CLI entrypoint users invoke.
- /controller: Python package that implements the CLI logic (controller/main.py), orchestrates parsing and requests to the API.
- /api: A Django project (“api/api”) exposing REST endpoints, loading templates, managing a database, and defining Celery tasks for rule evaluation.
- api/api/settings.py, urls.py, views.py – Django REST framework setup
- api/api/tasks.py – Celery task definitions
- api/builtin_templates – YAML rule definitions shipped with the project
- api/rust_syn_wrapper – Rust library (cargo) providing an AST generator via PyO3 or CLI
- /docker-compose*.yml, Dockerfiles: container definitions for local development (API + controller + message broker + database).
- scripts (install-radar.sh, update-radar.sh): installation and update helpers.
- /docs, /static: documentation and image assets – not part of the core runtime pipeline.

##### Key README Insights
- Confirms the two main runtimes: a CLI (“radar -p <folder>”) and a web/django–Celery service when run in Docker.
- Emphasizes the use of Python-based rule engine + YAML templates.
- Mentions integration via GitHub Actions or pre-commit hooks (external CI integration).

##### Detail & Precision Checklist
- Folder-to-component mapping (e.g., /controller → CLI; /api/api → API Server)
- Configuration surfaces: Dockerfiles, docker-compose, .env for broker/DB credentials
- Where builtin_templates live in the flow (loaded by API at startup)
- Error-handling or retry (Celery retries on failure) if space permits

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        RadarCLI["Radar CLI\n(radar script)"]:::cli
        ControllerMain["controller/main.py"]:::cli
        ControllerAPI["controller/api.py"]:::cli
        ControllerHelpers["controller/helpers.py"]:::cli
    end

    %% Parser Layer
    subgraph "Rust AST Parser\n(rust_syn_wrapper)"
        direction TB
        CargoToml["Cargo.toml"]:::parser
        CargoLock["Cargo.lock"]:::parser
        LibRs["lib.rs"]:::parser
    end

    %% API Server Layer
    subgraph "API Server\n(Django REST App)"
        direction TB
        Settings["settings.py"]:::api
        Urls["urls.py"]:::api
        Views["views.py"]:::api
        Serializers["serializers.py"]:::api
        Models["models.py"]:::api
        Admin["admin.py"]:::api
        ASGI["asgi.py"]:::api
        WSGI["wsgi.py"]:::api
        Manage["manage.py"]:::api
        Entrypoint["entrypoint.sh"]:::api
        Migrations["migrations/__init__.py"]:::db
    end

    %% Celery Workers Layer
    subgraph "Celery Workers"
        direction TB
        CeleryConfig["celery.py"]:::worker
        Tasks["tasks.py"]:::worker
    end

    %% Templates Store
    BuiltinTemplates["builtin_templates\n(*.yaml)"]:::datastore

    %% Broker & Database
    subgraph "Infrastructure"
        direction TB
        DockerCompose["docker-compose*.yml"]:::infra
        APIDockerfile["api/Dockerfile"]:::infra
        ControllerDockerfile["controller/Dockerfile"]:::infra
    end

    %% External CI Integrations
    subgraph "External CI Integrations"
        direction TB
        GHCR["ghcr.yml"]:::ci
        PipAudit["pip-audit.yml"]:::ci
        Pytest["pytest.yml"]:::ci
    end

    %% Main Flow
    RadarCLI -->|"invokes"| ControllerMain
    ControllerMain -->|"calls Parser"| LibRs
    ControllerMain -->|"HTTP POST AST JSON"| Views
    LibRs -->|"generates AST JSON"| ControllerMain
    Views -->|"enqueue tasks"| CeleryConfig
    CeleryConfig -->|"publish to broker"| DockerCompose
    Tasks -->|"consume tasks"| Views
    Tasks -->|"evaluate rules\n(load YAML from templates)"| BuiltinTemplates
    Tasks -->|"persist results"| Models
    ControllerMain -->|poll GET results| Views

    %% Click Events
    click RadarCLI "https://github.com/auditware/radar/tree/main/radar"
    click ControllerMain "https://github.com/auditware/radar/blob/main/controller/main.py"
    click ControllerAPI "https://github.com/auditware/radar/blob/main/controller/api.py"
    click ControllerHelpers "https://github.com/auditware/radar/blob/main/controller/helpers.py"
    click CargoToml "https://github.com/auditware/radar/blob/main/api/rust_syn_wrapper/Cargo.toml"
    click CargoLock "https://github.com/auditware/radar/blob/main/api/rust_syn_wrapper/Cargo.lock"
    click LibRs "https://github.com/auditware/radar/blob/main/api/rust_syn_wrapper/src/lib.rs"
    click Settings "https://github.com/auditware/radar/blob/main/api/api/settings.py"
    click Urls "https://github.com/auditware/radar/blob/main/api/api/urls.py"
    click Views "https://github.com/auditware/radar/blob/main/api/api/views.py"
    click Serializers "https://github.com/auditware/radar/blob/main/api/api/serializers.py"
    click Models "https://github.com/auditware/radar/blob/main/api/api/models.py"
    click Admin "https://github.com/auditware/radar/blob/main/api/api/admin.py"
    click ASGI "https://github.com/auditware/radar/blob/main/api/api/asgi.py"
    click WSGI "https://github.com/auditware/radar/blob/main/api/api/wsgi.py"
    click Manage "https://github.com/auditware/radar/blob/main/api/manage.py"
    click Entrypoint "https://github.com/auditware/radar/blob/main/api/entrypoint.sh"
    click CeleryConfig "https://github.com/auditware/radar/blob/main/api/api/celery.py"
    click Tasks "https://github.com/auditware/radar/blob/main/api/api/tasks.py"
    click BuiltinTemplates "https://github.com/auditware/radar/tree/main/api/builtin_templates"
    click DockerCompose "https://github.com/auditware/radar/blob/main/docker-compose.yml"
    click DockerCompose "https://github.com/auditware/radar/blob/main/docker-compose-dev.yml"
    click APIDockerfile "https://github.com/auditware/radar/tree/main/api/Dockerfile"
    click ControllerDockerfile "https://github.com/auditware/radar/tree/main/controller/Dockerfile"
    click Migrations "https://github.com/auditware/radar/blob/main/api/api/migrations/__init__.py"
    click GHCR "https://github.com/auditware/radar/blob/main/.github/workflows/ghcr.yml"
    click PipAudit "https://github.com/auditware/radar/blob/main/.github/workflows/pip-audit.yml"
    click Pytest "https://github.com/auditware/radar/blob/main/.github/workflows/pytest.yml"

    %% Styling
    classDef cli fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef parser fill:#D5F5E3,stroke:#196F3D,color:#145A32;
    classDef api fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    classDef worker fill:#E8DAEF,stroke:#6C3483,color:#4A235A;
    classDef datastore fill:#FADBD8,stroke:#C0392B,color:#641E16;
    classDef infra fill:#EBF5FB,stroke:#2E86C1,color:#1B4F72;
    classDef db fill:#FDEDEC,stroke:#922B21,color:#641E16;
    classDef ci fill:#F9EBEA,stroke:#AF7AC5,color:#512E5F;
```
