# lf-connectivity/isptoolbox architecture

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

- Interactive diagram: https://gitdiagram.com/lf-connectivity/isptoolbox
- Repository: https://github.com/lf-connectivity/isptoolbox

## Overview

##### Project Type & Purpose
- This is a full-stack, containerized web application (“ISP Toolbox”) that provides mapping and analytics tools (market evaluator, LOS-check, DSM export, network cost comparison).
- Backend: Django + Django REST Framework + Channels (websockets) + Celery for async tasks.
- Frontend: TypeScript/React-style SPA served from a static container.
- Infrastructure as Code: Terraform. Deployment: Docker/ECS on AWS (ALB, EC2, ECR, ECS), RDS (Postgres), ElastiCache (Redis), S3 for static assets. Lambdas at CloudFront Edge for custom request/response logic.

##### Architectural Patterns & Principles
- Layered separation:
- Presentation (browser, static container)
- API/Websocket (Django)
- Business logic (Celery tasks)
- Data (Postgres, Redis, S3)
- Message-driven async: Celery + Redis decouples long-running tasks.
- Infrastructure as code: Terraform modules for network, autoscaling, IAM, load-balancer.
- Container orchestration: ECS services, Docker Compose for local dev.

- Blue: External/client
- Green: Edge/Ingress
- Yellow: Compute services (Django, Node, Celery)
- Orange: Data stores (Postgres, Redis, S3)
- Gray: IaC/CI (Terraform, GitHub Actions)

##### Essential Details to Capture
- Reverse proxy (Nginx) sits in front of all services.
- WebSocket traffic handled by Django Channels, backed by Redis.
- Celery broker = Redis; results may live in Postgres or S3.
- Node-webserver handles map-specific middleware.
- Lambda@Edge functions apply custom logic at CloudFront.
- Terraform modules define autoscaling, networking, secrets, IAM.
- GitHub workflows build & push Docker images to ECR, then ECS deploy.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        Browser["Web Browser"]:::external
        E2E["Cypress E2E Tests"]:::external
    end
    click Browser "https://github.com/lf-connectivity/isptoolbox/tree/main/webserver/static/isptoolbox/"
    click E2E "https://github.com/lf-connectivity/isptoolbox/tree/main/cypress/"

    %% Edge & Ingress
    subgraph "Edge & Ingress"
        DNS["Route53 (DNS)"]:::edge
        CF["CloudFront"]:::edge
        LE1["Lambda@Edge viewer_request"]:::edge
        LE2["Lambda@Edge origin_response"]:::edge
        ALB["ALB"]:::edge
        NGINX["Nginx Reverse Proxy"]:::edge
    end
    click LE1 "https://github.com/lf-connectivity/isptoolbox/blob/main/lambda/edge/src/viewer_request/index.js"
    click LE2 "https://github.com/lf-connectivity/isptoolbox/blob/main/lambda/edge/src/origin_response/index.js"
    click NGINX "https://github.com/lf-connectivity/isptoolbox/tree/main/nginx/Dockerfile"
    click NGINX "https://github.com/lf-connectivity/isptoolbox/blob/main/nginx/nginx.default"
    click ALB "https://github.com/lf-connectivity/isptoolbox/blob/main/terraform/04_loadbalancer.tf"

    %% Compute Services
    subgraph "Compute Services"
        subgraph "API & WebSocket"
            DjangoApp["Django API & Channels (ECS)"]:::compute
            ORM["Django ORM"]:::compute
            DRF["DRF Endpoints"]:::compute
            Channels["Channels WebSocket"]:::compute
            Auth["Auth (socialaccount, SSO)"]:::compute
            CelInteg["Celery Integration"]:::compute
        end
        subgraph "Static & Node Webserver"
            Static["Static SPA Container"]:::compute
            NodeWS["Node Webserver"]:::compute
        end
        subgraph "Async Workers"
            RedisBroker["Redis (ElastiCache)"]:::data
            CelWorkers["Celery Workers (ECS)"]:::compute
        end
    end

    click DjangoApp "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/webserver/asgi.py"
    click ORM "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/webserver/settings.py"
    click DRF "https://github.com/lf-connectivity/isptoolbox/tree/main/webserver/workspace/api/views/"
    click Channels "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/IspToolboxApp/routing.py"
    click Auth "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/IspToolboxAccounts/backends.py"
    click Auth "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/IspToolboxAccounts/middleware.py"
    click CelInteg "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/celery_async/celery.py"
    click CelInteg "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/run_celery.py"
    click Static "https://github.com/lf-connectivity/isptoolbox/tree/main/webserver/static/isptoolbox/"
    click NodeWS "https://github.com/lf-connectivity/isptoolbox/blob/main/node-webserver/src/app.ts"
    click NodeWS "https://github.com/lf-connectivity/isptoolbox/blob/main/node-webserver/src/middleware/django_auth_middleware.ts"
    click RedisBroker "https://github.com/lf-connectivity/isptoolbox/tree/main/redis/Dockerfile"
    click RedisBroker "https://github.com/lf-connectivity/isptoolbox/blob/main/redis/redis.conf"
    click CelWorkers "https://github.com/lf-connectivity/isptoolbox/blob/main/terraform/templates/celery_app.json.tpl"

    %% Data Stores
    subgraph "Data Stores"
        Postgres["Postgres (RDS)"]:::data
        S3["S3 (Static & Assets)"]:::data
    end
    click Postgres "https://github.com/lf-connectivity/isptoolbox/blob/main/terraform/10_rds.tf"
    click S3 "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/IspToolboxApp/util/s3.py"
    click S3 "https://github.com/lf-connectivity/isptoolbox/blob/main/terraform/variables.tf"
    click S3 "https://github.com/lf-connectivity/isptoolbox/tree/main/webserver/static/potree/"

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        Terraform["Terraform IaC"]:::infra
        GitHubA["GitHub Actions"]:::infra
        ECR["ECR Registry"]:::infra
        DC["Docker Compose (Local)"]:::infra
        Entrypoints["Entrypoint Scripts"]:::infra
    end
    click Terraform "https://github.com/lf-connectivity/isptoolbox/tree/main/terraform/"
    click Terraform "https://github.com/lf-connectivity/isptoolbox/blob/main/terraform/README.md"
    click GitHubA "https://github.com/lf-connectivity/isptoolbox/tree/main/.github/workflows/"
    click ECR "https://github.com/lf-connectivity/isptoolbox/blob/main/scripts/buildnpush.sh"
    click ECR "https://github.com/lf-connectivity/isptoolbox/blob/main/scripts/deploy_latest_image_to_prod.sh"
    click DC "https://github.com/lf-connectivity/isptoolbox/blob/main/docker-compose.dev.yml"
    click Entrypoints "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/dev_entrypoint_django.sh"
    click Entrypoints "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/dev_entrypoint_celery.sh"
    click Entrypoints "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/test_entrypoint_django.sh"
    click Entrypoints "https://github.com/lf-connectivity/isptoolbox/blob/main/webserver/test_entrypoint_celery.sh"

    %% Connections
    Browser -->|HTTPS| DNS
    E2E -->|HTTPS| ALB
    DNS --> CF
    CF --> LE1
    LE1 --> CF
    CF --> LE2
    LE2 --> CF
    CF --> ALB
    ALB --> NGINX
    NGINX --> DjangoApp
    NGINX --> Static
    NGINX --> NodeWS
    DjangoApp --> ORM
    ORM --> Postgres
    DjangoApp --> DRF
    DRF --> Postgres
    DjangoApp --> Channels
    Channels --> RedisBroker
    DjangoApp --> RedisBroker
    DjangoApp --> CelInteg
    CelInteg --> CelWorkers
    CelWorkers --> RedisBroker
    CelWorkers --> Postgres
    CelWorkers --> S3
    Static --> Browser
    NodeWS --> Browser
    Terraform --> ALB
    Terraform --> Postgres
    Terraform --> RedisBroker
    Terraform --> S3
    Terraform --> ECR
    Terraform --> DjangoApp
    Terraform --> CelWorkers

    %% Styles
    classDef external fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef edge fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef compute fill:#FFF9C4,stroke:#F57F17,color:#F57F17
    classDef data fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef infra fill:#E0E0E0,stroke:#424242,color:#424242
```
