# owasp-blt/blt architecture

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

- Interactive diagram: https://gitdiagram.com/owasp-blt/blt
- Repository: https://github.com/owasp-blt/blt

## Overview

##### Project type and purpose
- This is a full-stack, MVT (Model-View-Template) Django web application called “OWASP BLT” (Bug-Bounty & Leaderboard Tool).
- It offers a public web frontend, a REST/API layer, WebSocket-based real-time features (chat/video), scheduled background tasks, and integrations with external services (Bitcoin node, GitHub, Slack, SendGrid, etc.).

##### Top-level components
a. End-users & Clients
- Web browsers (HTTP/HTTPS)
- Mobile clients (HTTP/HTTPS + WebSockets for video/chat)
b. Edge layer
- CDN or Load Balancer (serves static assets: CSS/JS, routes traffic to web servers)
- SSL termination
c. Web Application Layer (Django)
- ASGI server (Daphne/Uvicorn) for HTTP & WebSocket
- WSGI server (Gunicorn) for traditional HTTP
- Django project (“blt/” – settings, middleware, routing)
- Django apps (“website/” main app, “comments/”, plus any others)
- REST/API endpoints (website/api/views.py + serializers)
- WebSocket consumers (website/consumers.py)
- Management commands & scheduler (cron or Celery beat ↔ Django management/commands)
d. Data layer
- Relational database (PostgreSQL/MySQL) – holds users, issues, comments, bounties, etc.
- Cache / Channel Layer (Redis) – caching, session store, Django Channels layer
e. External-Service Integrations
- Bitcoin node (bitcoind service under BACON) – RPC calls from website/bitcoin_utils.py
- ord-server microservice (ordinals)
- GitHub API (fetch_repos, issues, PR stats via management commands)
- Slack API (incoming/outgoing webhooks, slash commands)
- SendGrid webhook receiver
- Google Cloud Storage (for screenshots)
- Blue Sky service (website/services/blue_sky_service.py)
f. Background/Batch Processing
- Scheduler (cron jobs or Celery beat)
- Workers (Celery or direct Django management command runners)

##### Relationships & data flow
- Clients ↔ Load Balancer (HTTP/HTTPS) ↔ ASGI/Wsgi servers ↔ Django apps
- Django apps ↔ Relational DB (ORM queries)
- Django apps ↔ Redis (cache, channel layer)
- Django (RPC client) → Bitcoin Node
- Django (HTTP client) → ord-server, GitHub, Slack, SendGrid, Blue Sky
- Scheduler → Django management commands → DB / external APIs

##### Key architectural patterns & design principles
- MVT (Django Model-View-Template) layered separation
- Asynchronous event handling via Django Channels (WebSocket consumers)
- Background tasks pattern (management commands or Celery tasks)
- External integration abstraction (services/blue_sky_service.py, bitcoin_utils.py)
- Twelve-factor app principles (12-Factor config via .env, Docker, Procfile)

##### Relevant technologies, frameworks & libraries
- Python 3 & Django (MVT)
- Django Channels (ASGI, WebSockets)
- Gunicorn / Daphne / Uvicorn (WSGI/ASGI servers)
- Redis (cache layer & channel layer)
- PostgreSQL (or another relational DB)
- Docker & docker-compose, Vagrant (development & deployment)
- GitHub Actions (CI/CD), Dependabot, CodeQL (security)
- bitcoind & ord-server (blockchain integration)
- External APIs: GitHub, Slack, SendGrid, Google Cloud Storage, Blue Sky

##### Don’t overthink—capture every moving piece
- Split the Django deployment into web servers + workers + scheduler.
- Both SQL DB and Redis as separate data stores.
- Bitcoin node & ord-server as internal microservices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Clients
    subgraph "Frontend Clients"
        Browser["Web Browser"]:::frontend
        Mobile["Mobile Client"]:::frontend
    end

    %% Edge Layer
    subgraph "Edge / CDN / Load Balancer"
        LB["CDN / Load Balancer\n(SSL Termination)"]:::app
    end

    %% Application Layer
    subgraph "Application Layer\n(Docker Cluster)"
        ASGI["ASGI Server\n(Daphne/Uvicorn)"]:::app
        WSGI["WSGI Server\n(Gunicorn)"]:::app
        subgraph "Django Project"
            Settings["blt/settings.py"]:::app
            URLs["blt/urls.py"]:::app
            Routing["blt/routing.py"]:::app
            Middleware1["domain.py"]:::app
            Middleware2["ip_restrict.py"]:::app
            Middleware3["user_visit_tracking.py"]:::app
            subgraph "Apps"
                Website["website/"]:::app
                Comments["comments/"]:::app
            end
        end
        APIViews["website/api/views.py"]:::app
        Serializers["website/serializers.py"]:::app
        Consumers["website/consumers.py"]:::app
    end

    %% Data Layer
    subgraph "Data Layer"
        Postgres["PostgreSQL"]:::data
        Redis["Redis\n(Cache & Channel Layer)"]:::data
    end

    %% External Services
    subgraph "External Services"
        BitcoinNode["bitcoind"]:::external
        OrdServer["ord-server"]:::external
        GitHub["GitHub API"]:::external
        Slack["Slack API"]:::external
        SendGrid["SendGrid Webhook"]:::external
        GCS["Google Cloud Storage"]:::external
        BlueSky["Blue Sky Service"]:::external
    end

    %% Background Tasks
    subgraph "Background Tasks"
        Scheduler["Cron / Celery Beat"]:::background
        ManagementCmds["website/management/commands/"]:::background
        BitcoinUtils["website/bitcoin_utils.py"]:::background
        BlueSkySvc["website/services/blue_sky_service.py"]:::background
    end

    %% Connections
    Browser -->|HTTP/HTTPS| LB
    Mobile -->|HTTP/HTTPS| LB
    Mobile -->|WS| LB
    LB -->|HTTP/HTTPS| ASGI
    LB -->|HTTP/HTTPS| WSGI
    ASGI -->|"routes HTTP"| URLs
    ASGI -->|"routes WS"| Routing
    WSGI -->|"routes HTTP"| URLs

    URLs -->|imports| Settings
    URLs -->|uses| Middleware1
    URLs -->|uses| Middleware2
    URLs -->|uses| Middleware3

    URLs -->|calls views| APIViews
    APIViews -->|uses| Serializers

    Routing -->|connects| Consumers

    Website -->|ORM queries| Postgres
    Comments -->|ORM queries| Postgres

    Website -->|cache/session| Redis
    Consumers -->|pub/sub| Redis

    Website -->|RPC calls| BitcoinNode
    Website -->|HTTP calls| OrdServer
    Website -->|HTTP calls| GitHub
    Website -->|HTTP calls| Slack
    Website -->|HTTP calls| SendGrid
    Website -->|HTTP calls| GCS
    Website -->|HTTP calls| BlueSky

    Scheduler -.->|triggers| ManagementCmds
    ManagementCmds -->|runs logic| Website
    ManagementCmds -->|uses| GitHub
    ManagementCmds -->|uses| Slack

    ManagementCmds -->|uses| Postgres

    Website -->|uses| BitcoinUtils
    Website -->|uses| BlueSkySvc

    %% Click Events
    click Settings "https://github.com/owasp-blt/blt/blob/main/blt/settings.py"
    click URLs "https://github.com/owasp-blt/blt/blob/main/blt/urls.py"
    click Routing "https://github.com/owasp-blt/blt/blob/main/blt/routing.py"
    click Middleware1 "https://github.com/owasp-blt/blt/blob/main/blt/middleware/domain.py"
    click Middleware2 "https://github.com/owasp-blt/blt/blob/main/blt/middleware/ip_restrict.py"
    click Middleware3 "https://github.com/owasp-blt/blt/blob/main/blt/middleware/user_visit_tracking.py"
    click ASGI "https://github.com/owasp-blt/blt/blob/main/blt/asgi.py"
    click WSGI "https://github.com/owasp-blt/blt/blob/main/blt/wsgi.py"
    click Website "https://github.com/owasp-blt/blt/tree/main/website/"
    click Comments "https://github.com/owasp-blt/blt/tree/main/comments/"
    click APIViews "https://github.com/owasp-blt/blt/blob/main/website/api/views.py"
    click Serializers "https://github.com/owasp-blt/blt/blob/main/website/serializers.py"
    click Consumers "https://github.com/owasp-blt/blt/blob/main/website/consumers.py"
    click ManagementCmds "https://github.com/owasp-blt/blt/tree/main/website/management/commands/"
    click BitcoinUtils "https://github.com/owasp-blt/blt/blob/main/website/bitcoin_utils.py"
    click BlueSkySvc "https://github.com/owasp-blt/blt/blob/main/website/services/blue_sky_service.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef app fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef background fill:#FFFF99,stroke:#333,stroke-width:1px
```
