# bugbasesecurity/pentest-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/bugbasesecurity/pentest-copilot
- Repository: https://github.com/bugbasesecurity/pentest-copilot

## Overview

##### Project Type and Purpose
- Pentest Copilot is a full-stack, browser-based AI-powered ethical hacking assistant.
- It follows a microservices/containerized architecture: Next.js frontend, Express/TypeScript backend, MongoDB, Redis, an AI API integration (OpenAI), and an optional Kali Linux container for pentesting.

##### File Structure
- Top-level directories:
- **frontend/**: Next.js 13 app using React, Ant Design, Redux Toolkit, React Query, Xterm (in-browser terminal), SCSS.
- **backend/**: Node.js + Express + TypeScript. Organized by controllers, routes, services, models (Mongoose), middlewares, utils.
- **kali/**: Dockerfile + entrypoint + tools.sh to build a Kali Linux container with SSH, OpenVPN, noVNC.
- **nginx/**: Reverse-proxy container.
- **assets/**: Static images and banners.
- Config & orchestration:
- **docker-compose.yml**: Defines services (frontend, backend, mongodb, redis, kali, nginx).
- **.env.template** files for each component.

##### Key Architecture Insights from README
- **Microservices**: Each service runs in its own container.
- **Data stores**: MongoDB for persistence, Redis for session/auth caching.
- **Real-time**: Socket.IO for live terminal, AI prompts/responses.
- **AI integration**: Backend calls OpenAI API (gpt-4/gpt-3.5).

##### Main Components & Their Roles
a. Client/browser (Next.js UI)
b. Frontend server (Next.js Node server)
c. Backend API server (Express/TypeScript)
d. Databases: MongoDB (persistent), Redis (cache/session)
e. External AI Service (OpenAI API)
f. Kali Container (SSH/VNC/OpenVPN endpoint + pentest tools)
g. Reverse Proxy (Nginx for TLS, routing)
h. Docker Compose (orchestration)

##### Component Interactions & Data Flow
- Browser ↔ Frontend: HTTP(S) requests, SSR/SSG, WebSocket (via Socket.IO client).
- Frontend ↔ Backend: REST API calls, WebSocket for real-time sessions.
- Backend ↔ MongoDB: via Mongoose for users, sessions, workspaces, todos.
- Backend ↔ Redis: session tokens, workspace state caching.
- Backend ↔ OpenAI API: HTTP calls to generate commands, summaries.
- Backend ↔ Kali Container: SSH or Socket.IO tunnel to execute commands, retrieve output.
- Browser ↔ Kali Container (indirect): Through backend & WebSocket, terminal emulation via Xterm.
- Frontend ↔ Reverse Proxy (Nginx): All incoming traffic funnels through Nginx (optional).

##### Architectural Patterns & Design Principles
- **Microservices + Containers**: Each logical service in its own Docker container.
- **Separation of Concerns**:
- UI layer (Next.js)
- API layer (Express)
- Data layer (MongoDB/Redis)
- Pentest environment (Kali)
- **Event-Driven Real-Time**: Socket.IO pub/sub for live terminal and AI feedback.
- **Agentic AI**: Backend orchestrates AI as an autonomous agent to run commands.
- **MVC on Backend**: Controllers → Routes → Services → Models.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Docker Network"
        direction TB
        nginx["Nginx Reverse Proxy"]:::infra
        click nginx "https://github.com/bugbasesecurity/pentest-copilot/tree/main/nginx/Dockerfile"
        click nginx "https://github.com/bugbasesecurity/pentest-copilot/blob/main/nginx/nginx.conf"

        subgraph "Frontend Container"
            direction TB
            browser["Browser (Next.js UI)"]:::ui
            frontend["Frontend Server (Next.js)"]:::ui
            click frontend "https://github.com/bugbasesecurity/pentest-copilot/tree/main/frontend/Dockerfile"
            click frontend "https://github.com/bugbasesecurity/pentest-copilot/blob/main/frontend/package.json"
            click frontend "https://github.com/bugbasesecurity/pentest-copilot/blob/main/frontend/next.config.js"

            subgraph "Frontend Code"
                direction TB
                app["App Folder"]:::ui
                components["Components Folder"]:::ui
                click app "https://github.com/bugbasesecurity/pentest-copilot/tree/main/frontend/src/app"
                click components "https://github.com/bugbasesecurity/pentest-copilot/tree/main/frontend/src/components"
            end
        end

        subgraph "Backend Container"
            direction TB
            backend["Backend API Server (Express+TS)"]:::api
            click backend "https://github.com/bugbasesecurity/pentest-copilot/tree/main/backend/src"

            subgraph "Controllers & Middleware"
                direction TB
                authCtrl["auth.controller.ts"]:::api
                verifySession["VerifySession.middleware.ts"]:::api
                click authCtrl "https://github.com/bugbasesecurity/pentest-copilot/blob/main/backend/src/controllers/auth.controller.ts"
                click verifySession "https://github.com/bugbasesecurity/pentest-copilot/blob/main/backend/src/middlewares/VerifySession.middleware.ts"
            end

            subgraph "Services"
                direction TB
                proxySocket["proxysocket.service.ts"]:::api
                proxy["proxy.services.ts"]:::api
                copilotSvc["copilot.services.ts"]:::api
                click proxySocket "https://github.com/bugbasesecurity/pentest-copilot/blob/main/backend/src/services/proxysocket.service.ts"
                click proxy "https://github.com/bugbasesecurity/pentest-copilot/blob/main/backend/src/services/proxy.services.ts"
                click copilotSvc "https://github.com/bugbasesecurity/pentest-copilot/blob/main/backend/src/services/copilot.services.ts"
            end

            subgraph "Utils & Integration"
                direction TB
                redisStore["Redis Store"]:::api
                openaiCfg["OpenAI Config"]:::api
                click redisStore "https://github.com/bugbasesecurity/pentest-copilot/blob/main/backend/src/utils/redis/store.ts"
                click openaiCfg "https://github.com/bugbasesecurity/pentest-copilot/blob/main/backend/src/utils/openai/config.ts"
            end

            subgraph "Models"
                direction TB
                userModel["User Model"]:::api
                click userModel "https://github.com/bugbasesecurity/pentest-copilot/blob/main/backend/src/models/User/User.model.ts"
            end
        end

        subgraph "Data Layer"
            direction TB
            mongodb["MongoDB"]:::db
            redis["Redis Cache"]:::db
        end

        openai["OpenAI API"]:::external
        kali["Kali Pentest Container"]:::pentest
        click kali "https://github.com/bugbasesecurity/pentest-copilot/tree/main/kali/Dockerfile"
        click kali "https://github.com/bugbasesecurity/pentest-copilot/blob/main/kali/entrypoint.sh"
        click kali "https://github.com/bugbasesecurity/pentest-copilot/blob/main/kali/tools.sh"

        dockerCompose["docker-compose.yml"]:::infra
        click dockerCompose "https://github.com/bugbasesecurity/pentest-copilot/blob/main/docker-compose.yml"
    end

    %% Connections
    browser -->|"HTTPS / WS"| nginx
    nginx -->|"HTTP/HTTPS"| frontend
    frontend -->|"REST / WebSocket"| backend
    backend -->|"Mongoose"| mongodb
    backend -->|"Redis Cache"| redis
    backend -->|"OpenAI HTTP"| openai
    backend -->|"SSH / WebSocket"| kali

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef api fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20;
    classDef db fill:#FFF3E0,stroke:#E65100,color:#E65100;
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A;
    classDef pentest fill:#FFEBEE,stroke:#B71C1C,color:#B71C1C;
    classDef infra fill:#ECEFF1,stroke:#455A64,color:#455A64;
```
