# hassangar/webguard architecture

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

- Interactive diagram: https://gitdiagram.com/hassangar/webguard
- Repository: https://github.com/hassangar/webguard

## Overview

##### Project type and purpose
- This is a full-stack, modular Django web application named “webguard.”
- Its feature set includes user authentication, dashboards, recon notes, scan engines, scanning orchestration, target management, and reporting—i.e., a platform to manage security scans, view results, and interact with external services (e.g., HackerOne, LLM toolkits).

##### File structure
- Top-level orchestration:
- Docker and compose files (`Dockerfile`, `docker-compose.yml`, `docker-compose.dev.yml`, `docker-compose.setup.yml`)
- Nginx config in `config/nginx/webguard.conf`
- Certificate management (`certs/`)
- Shell scripts (`install.sh`, `update.sh`, `scripts/uninstall.sh`)
- Core application under `web/`:
- Django project root: `manage.py`, `webGuard/` (settings, celery config, wsgi, tasks, middleware, utilities)
- Apps: `api`, `dashboard`, `login`, `recon_note`, `scanEngine`, `startScan`, `targetApp`
- Global static assets and templates in `web/static` and `web/templates`
- Requirements pinned in `web/requirements.txt`
- Asynchronous tasks via Celery (`webGuard/celery.py`, `webGuard/tasks.py`, entrypoint scripts in `web/`).

##### Supplementary README insights
- Minimal README, but file names signal integration with external tools (HackerOne), background jobs (Celery), and a decoupled front-end (JS widgets, templates).

- Rounded rectangle for containers (Nginx, Django, Celery, DB)
- Interactions:
- “enqueue scan job,” “fetch scan results,” “render dashboard,” “call LLM API.”

##### Detail without over-fragmentation
- Infrastructure services separately but indicate the Docker network connecting them
- Volumes for persistent storage (certs, DB data, logs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Client Layer"
        Browser("Browser / API Client"):::client
    end

    %% Infrastructure
    subgraph "Infrastructure Layer"
        Nginx["Nginx:443"]:::proxy
        DockerCompose["docker-compose.yml"]:::infra
        DCDev["docker-compose.dev.yml"]:::infra
        DCSetup["docker-compose.setup.yml"]:::infra
        DFRoot["Dockerfile (root)"]:::infra
        DFWeb["web/Dockerfile"]:::infra
        Makefile["Makefile"]:::infra
        Install["install.sh"]:::infra
        Update["update.sh"]:::infra
        Uninstall["scripts/uninstall.sh"]:::infra
        Certs["certs/"]:::infra
        Volumes["Volumes (certs, logs, static)"]:::infra
        DB["PostgreSQL/MySQL"]:::db
        Broker["Redis/RabbitMQ (Broker)"]:::broker
    end

    %% Application Services
    subgraph "Application Layer"
        Nginx -->|HTTPS| DjangoApp
        DjangoApp["Django App (Gunicorn:8000)"]:::backend
        DjangoApp -->|Reads/Writes| DB
        DjangoApp -->|Enqueue Task| Broker
        Broker -->|Task Message| CeleryWorker
        CeleryWorker["Celery Worker"]:::worker
        CeleryWorker -->|Updates| DB
    end

    %% Modules inside Django
    subgraph "Django Application Modules"
        API["REST API (api/)"]:::module
        Auth["Authentication (login/)"]:::module
        Dashboard["Dashboard (dashboard/)"]:::module
        Recon["Recon Notes (recon_note/)"]:::module
        ScanEng["Scan Engine (scanEngine/)"]:::module
        StartScan["Scan Orchestration (startScan/)"]:::module
        Target["Target Management (targetApp/)"]:::module
    end

    DjangoApp -->|HTTP calls| API
    DjangoApp -->|HTTP calls| Auth
    DjangoApp -->|HTTP calls| Dashboard
    DjangoApp -->|HTTP calls| Recon
    DjangoApp -->|HTTP calls| ScanEng
    DjangoApp -->|HTTP calls| StartScan
    DjangoApp -->|HTTP calls| Target

    %% Static and Templates
    Nginx -->|Serves| Static["Static Assets"]:::static
    Nginx -->|Serves| Templates["Shared Templates"]:::template

    %% External Services
    subgraph "External Integrations"
        HackerOne["HackerOne API"]:::external
        LLMSvc["LLM Services"]:::external
        ExternalScanners["External Scan Engines"]:::external
    end

    DjangoApp -->|Sync API calls| HackerOne
    DjangoApp -->|Sync API calls| LLMSvc
    CeleryWorker -->|Async Calls| ExternalScanners
    CeleryWorker -->|Async Calls| LLMSvc

    %% Click events
    click Nginx "https://github.com/hassangar/webguard/blob/main/config/nginx/webguard.conf"
    click DockerCompose "https://github.com/hassangar/webguard/blob/main/docker-compose.yml"
    click DCDev "https://github.com/hassangar/webguard/blob/main/docker-compose.dev.yml"
    click DCSetup "https://github.com/hassangar/webguard/blob/main/docker-compose.setup.yml"
    click DFRoot "https://github.com/hassangar/webguard/tree/main/Dockerfile"
    click DFWeb "https://github.com/hassangar/webguard/tree/main/web/Dockerfile"
    click Makefile "https://github.com/hassangar/webguard/tree/main/Makefile"
    click Install "https://github.com/hassangar/webguard/blob/main/install.sh"
    click Update "https://github.com/hassangar/webguard/blob/main/update.sh"
    click Uninstall "https://github.com/hassangar/webguard/blob/main/scripts/uninstall.sh"
    click Certs "https://github.com/hassangar/webguard/tree/main/certs/"
    click DjangoApp "https://github.com/hassangar/webguard/blob/main/web/manage.py"
    click Broker "https://github.com/hassangar/webguard/blob/main/web/webGuard/celery.py"
    click CeleryWorker "https://github.com/hassangar/webguard/blob/main/web/celery-entrypoint.sh"
    click API "https://github.com/hassangar/webguard/blob/main/web/api/urls.py"
    click Auth "https://github.com/hassangar/webguard/blob/main/web/login/views.py"
    click Dashboard "https://github.com/hassangar/webguard/blob/main/web/dashboard/views.py"
    click Recon "https://github.com/hassangar/webguard/blob/main/web/recon_note/views.py"
    click ScanEng "https://github.com/hassangar/webguard/blob/main/web/scanEngine/views.py"
    click StartScan "https://github.com/hassangar/webguard/blob/main/web/startScan/views.py"
    click Target "https://github.com/hassangar/webguard/blob/main/web/targetApp/views.py"
    click Static "https://github.com/hassangar/webguard/tree/main/web/static/"
    click Templates "https://github.com/hassangar/webguard/tree/main/web/templates/"
    
    %% Styles
    classDef client fill:#D6E9FE,stroke:#2B5CA4,stroke-width:1px
    classDef proxy fill:#FEF3D6,stroke:#D19A00,stroke-width:1px
    classDef infra fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef db fill:#FFF3E0,stroke:#E65100,stroke-width:1px
    classDef broker fill:#E3F2FD,stroke:#1565C0,stroke-width:1px,stroke-dasharray: 5 5
    classDef backend fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px
    classDef worker fill:#FCE4EC,stroke:#C2185B,stroke-width:1px,stroke-dasharray: 5 5
    classDef module fill:#E0F7FA,stroke:#006064,stroke-width:1px
    classDef static fill:#FFFDE7,stroke:#F9A825,stroke-width:1px
    classDef template fill:#F1F8E9,stroke:#558B2F,stroke-width:1px
    classDef external fill:#ECEFF1,stroke:#607D8B,stroke-width:1px,stroke-dasharray: 5 5
```
