# cisagov/pentest-reporting-engine architecture

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

- Interactive diagram: https://gitdiagram.com/cisagov/pentest-reporting-engine
- Repository: https://github.com/cisagov/pentest-reporting-engine

## Overview

##### Project Type and Purpose
- This is a full-stack, containerized web application: the “Risk & Vulnerability Assessment Reporting Engine” (RE).
- Purpose: provide a Django-based backend (with REST API and HTML templates), a Vue3/Tailwind CSS frontend, and a report-generation engine for security assessment deliverables ( Word/PPTX/CSV).
- It’s packaged for both development and production via Docker Compose, with CLI tooling (ptp.py) to orchestrate setup, backup, restore, and container lifecycle.

##### File Structure Analysis
- Top-level “pentestportal” & “ptportal” directories: Django project (`settings.py`, `wsgi.py`) plus a Django app (`models`, `views`, `templates`, `static`, `forms`).
- “report_gen” directory: core report-generation modules and templates (Word, PPTX, CSV).
- “docker/” folder: Dockerfiles for dev (web & DB), prod (web, DB, nginx), env files, and helper scripts.
- “node/” and “node/dependencies/components-vue3”: bundled Vue3 component library + Tailwind CSS assets for the frontend.
- Top-level CLI script `ptp.py` and Makefile for high-level operations (run, dev, backup, restore, etc.).
- Configuration files: docker-compose.yml (dev) and docker-compose.prod.yml (prod), Nginx config, Python lint/format configs.

##### README Insights
- The README details prerequisites (Docker, Docker-Compose, Python, Django), setup steps (ptp.py run/dev), backup/restore via CLI, API endpoints, and development guidance.
- Emphasis on Docker Compose spinning up three services: `web` (Django app), `db` (PostgreSQL or similar), and `nginx` (reverse proxy/static server in prod).

##### Detail Guidance
- Network boundaries (Docker network), volume mounts (code, static, media)
- Docker Compose roles: which Compose YAML spins up which containers (dev vs. prod)
- Call out live-reload volume mounts in dev vs. baked-in code in prod images
- Ptp.py command flow for common operations (e.g., “ptp.py run → docker-compose up”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client Tier"
        browser["Browser"]:::client
        cli["CLI (ptp.py)"]:::client
    end

    %% Orchestration Layer
    subgraph "Orchestration"
        docker_api["Docker Engine API Wrapper"]:::app
        docker_engine["Docker Engine"]:::app
        compose_dev["docker-compose.yml"]:::app
        compose_prod["docker-compose.prod.yml"]:::app
        make["Makefile"]:::app
        subgraph "Dockerfiles"
            dev_web_df["Dockerfile.web (dev)"]:::app
            dev_db_df["Dockerfile.db (dev)"]:::app
            prod_web_df["Dockerfile.web (prod)"]:::app
            prod_db_df["Dockerfile.db (prod)"]:::app
            prod_nginx_df["Dockerfile.nginx"]:::app
            nginx_conf["nginx.conf"]:::app
        end
    end

    %% Application Tier
    subgraph "Application Tier"
        nginx["nginx (Container)"]:::app
        web["web (Django + Gunicorn)"]:::app
        subgraph "Django Source"
            settings["pentestportal/settings.py"]:::app
            wsgi["pentestportal/wsgi.py"]:::app
            urls["pentestportal/urls.py"]:::app
            ptportal_models["ptportal/models/"]:::app
            ptportal_api_urls["ptportal/api/urls.py"]:::app
            ptportal_api_views["ptportal/api/views.py"]:::app
            ptportal_serializers["ptportal/serializers.py"]:::app
            ptportal_views["ptportal/views/"]:::app
            ptportal_forms["ptportal/forms/"]:::app
            ptportal_mgmt["ptportal/management/commands/"]:::app
            ptportal_middleware["ptportal/middleware.py"]:::app
            ptportal_context["ptportal/context_processors.py"]:::app
            ptportal_urls["ptportal/urls.py"]:::app
            templates["ptportal/templates/ptportal/"]:::app
            static["ptportal/static/"]:::app
            reportgen["report_gen/"]:::app
        end
    end

    %% Data Tier
    subgraph "Data Tier"
        db["db (PostgreSQL)"]:::data
        filevol["File Store (Templates & Reports)"]:::data
    end

    %% Connections
    CLI -->|"uses API"| docker_api
    docker_api --> docker_engine
    make --> docker_engine
    compose_dev --> docker_engine
    compose_prod --> docker_engine
    compose_dev --> dev_web_df
    compose_dev --> dev_db_df
    compose_prod --> prod_web_df
    compose_prod --> prod_db_df
    compose_prod --> prod_nginx_df
    compose_prod --> nginx_conf

    browser -->|"HTTPS"| nginx
    nginx -->|"HTTP"| web
    web -->|"TCP/5432"| db
    web -->|"FS Volume"| filevol

    web --> settings
    web --> wsgi
    web --> urls
    web --> ptportal_models
    web --> ptportal_api_urls
    web --> ptportal_api_views
    web --> ptportal_serializers
    web --> ptportal_views
    web --> ptportal_forms
    web --> ptportal_mgmt
    web --> ptportal_middleware
    web --> ptportal_context
    web --> ptportal_urls
    web --> templates
    web --> static
    web --> reportgen

    %% Click Events
    click cli "https://github.com/cisagov/pentest-reporting-engine/blob/develop/ptp.py"
    click docker_api "https://github.com/cisagov/pentest-reporting-engine/blob/develop/docker/docker_api.py"
    click compose_dev "https://github.com/cisagov/pentest-reporting-engine/blob/develop/docker-compose.yml"
    click compose_prod "https://github.com/cisagov/pentest-reporting-engine/blob/develop/docker-compose.prod.yml"
    click make "https://github.com/cisagov/pentest-reporting-engine/tree/develop/Makefile"
    click dev_web_df "https://github.com/cisagov/pentest-reporting-engine/blob/develop/docker/dev/Dockerfile.web"
    click dev_db_df "https://github.com/cisagov/pentest-reporting-engine/blob/develop/docker/dev/Dockerfile.db"
    click prod_web_df "https://github.com/cisagov/pentest-reporting-engine/blob/develop/docker/prod/Dockerfile.web"
    click prod_db_df "https://github.com/cisagov/pentest-reporting-engine/blob/develop/docker/prod/Dockerfile.db"
    click prod_nginx_df "https://github.com/cisagov/pentest-reporting-engine/blob/develop/docker/prod/nginx/Dockerfile.nginx"
    click nginx_conf "https://github.com/cisagov/pentest-reporting-engine/blob/develop/docker/prod/nginx/conf/nginx.conf"
    click settings "https://github.com/cisagov/pentest-reporting-engine/blob/develop/pentestportal/settings.py"
    click wsgi "https://github.com/cisagov/pentest-reporting-engine/blob/develop/pentestportal/wsgi.py"
    click urls "https://github.com/cisagov/pentest-reporting-engine/blob/develop/pentestportal/urls.py"
    click ptportal_models "https://github.com/cisagov/pentest-reporting-engine/tree/develop/ptportal/models/"
    click ptportal_api_urls "https://github.com/cisagov/pentest-reporting-engine/blob/develop/ptportal/api/urls.py"
    click ptportal_api_views "https://github.com/cisagov/pentest-reporting-engine/blob/develop/ptportal/api/views.py"
    click ptportal_serializers "https://github.com/cisagov/pentest-reporting-engine/blob/develop/ptportal/serializers.py"
    click ptportal_views "https://github.com/cisagov/pentest-reporting-engine/tree/develop/ptportal/views/"
    click ptportal_forms "https://github.com/cisagov/pentest-reporting-engine/tree/develop/ptportal/forms/"
    click ptportal_mgmt "https://github.com/cisagov/pentest-reporting-engine/tree/develop/ptportal/management/commands/"
    click ptportal_middleware "https://github.com/cisagov/pentest-reporting-engine/blob/develop/ptportal/middleware.py"
    click ptportal_context "https://github.com/cisagov/pentest-reporting-engine/blob/develop/ptportal/context_processors.py"
    click ptportal_urls "https://github.com/cisagov/pentest-reporting-engine/blob/develop/ptportal/urls.py"
    click templates "https://github.com/cisagov/pentest-reporting-engine/tree/develop/ptportal/templates/ptportal/"
    click static "https://github.com/cisagov/pentest-reporting-engine/tree/develop/ptportal/static/"
    click reportgen "https://github.com/cisagov/pentest-reporting-engine/tree/develop/report_gen/"

    %% Styles
    classDef client 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
```
