# garytan/gophish architecture

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

- Interactive diagram: https://gitdiagram.com/garytan/gophish
- Repository: https://github.com/garytan/gophish

## Overview

##### Project type and purpose
- This is a full-stack web application written in Go, called Gophish, an open-source phishing toolkit.
- Its core purpose is to let operators create and launch phishing campaigns, track responses, and manage users/templates.

##### File structure
- Top-level Go modules:
- gophish.go (entry point)
- controllers/ (HTTP handlers, REST API)
- models/ (ORM-like data models)
- db/ (database drivers & migrations for MySQL and SQLite)
- auth/, config/, context/, middleware/ (request pipeline, sessions, rate-limiting)
- static/, templates/ (frontend assets and HTML templates)
- mailer/, dialer/, imap/ (components that send mail, manage SMTP/IMAP connections)
- worker/ (background job processing – scheduling campaigns, sending events)
- webhook/ (outgoing webhooks to report events)
- Deployment/config: Dockerfile, ansible-playbook/, webpack.config.js

##### README for additional insights
- Confirms Go v1.10+, binary release, Docker support, default UI on port 3333

a. Main components
1. Web UI & REST API
- Static Assets (JS, CSS) served from /static
- HTML templates in /templates
- Controllers (controllers/api/*.go + controllers/route.go)
2. Application Server
- Authentication & Session Management (auth/, middleware/)
- Business Logic (controllers/, worker/, webhook/)
3. Database
- Choose MySQL or SQLite (db/db_mysql or db/db_sqlite3)
- Migrations under db/…/migrations
- Models layer interacts with DB (models/*.go)
4. Mail Subsystems
- dialer/ (handles SMTP connections configured via controllers/api/smtp.go)
- mailer/ (constructs & sends email messages)
- imap/ (tracks inbound responses via IMAP polling)
5. Worker & Scheduler
- Background tasks (worker/worker.go) → enqueues/sends campaigns, processes results
6. External Services
- SMTP server (outbound mail)
- IMAP server (inbound tracking)
- Optional webhooks to external endpoints

b. Relationships and interactions
- User’s browser → HTTP(S) → Web UI / API endpoints
- API calls → Controllers → Models → Database
- Campaign scheduling → Worker pulls tasks → dialer/mailer → SMTP → Recipient inbox
- Response tracking → imap monitor polls IMAP → writes events → Database
- On certain events → webhook component → HTTP POST → External systems
- Ansible/Docker used to provision the entire stack (app + DB + reverse proxy)

c. Architectural patterns & design principles
- MVC-style separation: templates (view), controllers (controller), models (model)
- Layered architecture: HTTP layer → business logic → persistence layer
- Modular services for mail sending, IMAP processing, background work
- Configuration-driven (config.json, env vars, ansible, Docker)
- Extensible via REST API & webhooks

d. Key technologies & frameworks
- Go standard library net/http, html/template
- Gulp/Webpack for JS asset bundling
- MySQL or SQLite3 databases
- Ansible & Docker for deployment
- Third-party Go libraries for sessions, rate limiting

##### Elements
- Green for user-facing components (Browser, UI)
- Blue for backend services (API, worker, mailer)
- Orange for persistence (DB, migrations)
- Gray for external systems (SMTP & IMAP servers, webhook endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["User Browser"]:::frontend
        Static["Static Assets"]:::frontend
        Templates["HTML Templates"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Entry["gophish.go (Entry Point)"]:::backend
        Config["Configuration Loader"]:::backend
        Context["Request Context Utilities"]:::backend
        Auth["Authentication & Session Management"]:::backend
        Middleware["Middleware Pipeline"]:::backend
        Controllers["REST API Controllers"]:::backend
        Models["Models (Persistence Layer)"]:::backend
        Worker["Background Worker & Scheduler"]:::backend
        WebhookComp["Webhook Dispatcher"]:::backend
        MailSub["Mail Subsystems"]:::backend
        subgraph "Mail Subsystems"
            direction TB
            Dialer["SMTP Dialer"]:::backend
            Mailer["Mailer"]:::backend
            IMAP["IMAP Monitor"]:::backend
        end
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DBOptions["Database Drivers & Migrations"]:::persistence
        MySQL["MySQL (db/db_mysql)"]:::persistence
        SQLite["SQLite (db/db_sqlite3)"]:::persistence
    end

    %% External Systems
    subgraph "External Services"
        direction TB
        SMTPServer["SMTP Server"]:::external
        IMAPServer["IMAP Server"]:::external
        WebhookExt["External Webhook Endpoints"]:::external
    end

    %% Deployment
    subgraph "Deployment & Provisioning"
        direction TB
        Docker["Dockerfile"]:::config
        Ansible["Ansible Playbooks"]:::config
    end

    %% Relationships
    Browser -->|"GET /static"| Static
    Browser -->|"GET HTML"| Templates
    Browser -->|"HTTP(S) Requests"| Entry
    Entry --> Config
    Config --> Auth
    Auth --> Middleware
    Middleware --> Context
    Context --> Controllers
    Controllers --> Models
    Controllers --> Worker
    Controllers --> WebhookComp
    Worker --> Dialer
    Worker --> Mailer
    IMAP --> Models
    Dialer --> SMTPServer
    Mailer --> SMTPServer
    IMAP --> IMAPServer
    WebhookComp --> WebhookExt
    Models --> DBOptions
    DBOptions --> MySQL
    DBOptions --> SQLite
    Entry --> Docker
    Entry --> Ansible

    %% Click Events
    click Entry "https://github.com/garytan/gophish/blob/master/gophish.go"
    click Static "https://github.com/garytan/gophish/tree/master/static/"
    click Templates "https://github.com/garytan/gophish/tree/master/templates/"
    click Controllers "https://github.com/garytan/gophish/blob/master/controllers/route.go"
    click Controllers "https://github.com/garytan/gophish/blob/master/controllers/api/campaign.go"
    click Controllers "https://github.com/garytan/gophish/blob/master/controllers/api/smtp.go"
    click Controllers "https://github.com/garytan/gophish/blob/master/controllers/api/webhook.go"
    click Auth "https://github.com/garytan/gophish/blob/master/auth/auth.go"
    click Middleware "https://github.com/garytan/gophish/blob/master/middleware/middleware.go"
    click Middleware "https://github.com/garytan/gophish/blob/master/middleware/ratelimit/ratelimit.go"
    click Context "https://github.com/garytan/gophish/blob/master/context/context.go"
    click Config "https://github.com/garytan/gophish/blob/master/config/config.go"
    click Config "https://github.com/garytan/gophish/blob/master/ansible-playbook/roles/gophish/files/config.json"
    click Models "https://github.com/garytan/gophish/blob/master/models/campaign.go"
    click Models "https://github.com/garytan/gophish/blob/master/models/user.go"
    click Models "https://github.com/garytan/gophish/blob/master/models/webhook.go"
    click DBOptions "https://github.com/garytan/gophish/tree/master/db/db_mysql/"
    click DBOptions "https://github.com/garytan/gophish/tree/master/db/db_sqlite3/"
    click Dialer "https://github.com/garytan/gophish/blob/master/dialer/dialer.go"
    click Mailer "https://github.com/garytan/gophish/blob/master/mailer/mailer.go"
    click IMAP "https://github.com/garytan/gophish/blob/master/imap/imap.go"
    click IMAP "https://github.com/garytan/gophish/blob/master/imap/monitor.go"
    click Worker "https://github.com/garytan/gophish/blob/master/worker/worker.go"
    click WebhookComp "https://github.com/garytan/gophish/blob/master/webhook/webhook.go"
    click Docker "https://github.com/garytan/gophish/tree/master/Dockerfile"
    click Ansible "https://github.com/garytan/gophish/tree/master/ansible-playbook/"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064
    classDef backend fill:#e3f2fd,stroke:#1e88e5,color:#1e88e5
    classDef persistence fill:#fff3e0,stroke:#fb8c00,color:#bf360c
    classDef external fill:#f5f5f5,stroke:#9e9e9e,color:#424242
    classDef config fill:#f3e5f5,stroke:#8e24aa,color:#6a0080
```
