# factionsecurity/faction architecture

> Architecture diagram of the GitHub repository factionsecurity/faction, 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/factionsecurity/faction
- Repository: https://github.com/factionsecurity/faction

## Overview

##### Project Type & Purpose
- This is a full-stack, Java-based web application (monolithic at the service level) packaged as a WAR and deployed via Docker (Tomcat).
- Frontend: JSPs, static assets (CSS/JS), Webpack build, served by the Java web server.
- Backend: Struts/Spring controllers (com.fuse.actions, com.fuse.api, com.fuse.servlets), service/business logic, DAO layer (Hibernate/JPA), extensibility API, report-generation engine (docx4j).
- Persistence: Primary relational database (configured via persistence.xml + Hibernate), plus optional MongoDB for some features (noted in README).
- Integrations: LDAP/OAuth for authentication, SMTP for email, external Burp Suite extension via REST API.

##### File Structure (High-Level)
- Top level: Docker + Maven configs (Dockerfile, docker-compose.yml, pom.xml).
- WebContent: all UI (JSP + static libs + Webpack output).
- src/com/fuse: Java code—actions (MVC controllers), api (REST endpoints), dao (data access), utils, servlets, extenderapi, tasks, reporting.
- tests & unittests: JUnit tests for core workflows and extension API.

a. Users & Clients
- Browser clients (UI)
- Burp Suite extension (third-party PenTest tool)
- External systems calling the REST API

b. Frontend Layer
- Static Asset Server (Tomcat serves WebContent/dist, JSP engine).
- JSP Views + Taglibs + Webpack-generated JS/CSS

c. Backend Layer (Single Java Service)
- Web Container (Tomcat inside Docker)
- MVC Controllers (Struts/Spring)
- REST API Controllers (com.fuse.api)
- Business Services + Extender API (com.fuse.extenderapi)
- Report Generation Module (docx4j)
- Asynchronous Task Queue (EmailThread, ReportGenThread)

d. Data Layer
- Primary RDBMS (configured via src/META-INF/persistence.xml, Hibernate)
- Optional MongoDB service (noted as a requirement, spun up in docker-compose)

e. External Integrations
- LDAP / OAuth2.0 Identity Provider
- SMTP Mail Server
- S3 (for report templates, if configured)
- Burp Suite Extension (via REST over HTTPS)

##### Relationships & Data Flows
- Browser → HTTP(S) → Tomcat/JSP (UI requests, form posts, AJAX)
- Tomcat Controllers → Service Layer → DAO → RDBMS (CRUD on assessments, vulnerabilities, users)
- Report requests → Reporting Module → docx4j → generated DOCX delivered to browser or stored
- Task Queue → asynchronous threads → SMTP (email notifications)
- REST API endpoints → consumed by Burp Suite extension or other clients
- Authentication flows → Tomcat → LDAP/OAuth provider → session token/cookie
- Extensions (custom JARs) loaded by Extender API → invoked at event hooks

##### Architectural Patterns & Principles
- Layered Architecture (Presentation → Controller → Service → DAO → Persistence)
- Plugin / Extension Pattern (ExtensionClassLoader + ExtensionActionListener)
- Asynchronous Task Processing (thread pool executor for email, report generation)
- MVC via Struts/Spring + REST via JAX-RS controllers
- Configuration via Docker Compose for environment isolation

##### Final Checklist
[ ] All major tiers (UI, App, Data, External) clearly labeled
[ ] Notes on async flows (task queue threads)
[ ] Call-outs for extension/plugin loading

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker & Build"
        Dockerfile["Dockerfile"]:::docker
        DockerCompose["docker-compose.yml"]:::docker
        DockerComposeDev["docker-compose-dev.yml"]:::docker
        Entrypoint["entrypoint.sh"]:::docker
        POM["pom.xml"]:::docker
    end

    subgraph "Frontend Layer"
        JSP["WebContent/index.jsp"]:::frontend
        JSPDir["WebContent/WEB-INF/jsp/"]:::frontend
        Dist["WebContent/dist/"]:::frontend
        Bootstrap["WebContent/bootstrap/"]:::frontend
        Plugins["WebContent/plugins/"]:::frontend
        WebpackProd["WebContent/webpack.config.js"]:::frontend
        WebpackDev["WebContent/webpack.config-dev.js"]:::frontend
    end

    subgraph "Backend Layer"
        WebContainer["Tomcat Web Container\n(Java11, Struts, Spring, Hibernate, docx4j)"]:::backend
        subgraph Controllers
            MVC["MVC Controllers"]:::backend
            REST["REST API Controllers"]:::backend
        end
        Services["Business Services & Utilities"]:::backend
        DAO["DAO Layer"]:::backend
        Extender["Extensibility API"]:::backend
        Reporting["Report Generation Module"]:::backend
        Tasks["Asynchronous Task Queue"]:::backend
        Servlets["Servlets"]:::backend
        Taglib["Tag Libraries"]:::backend
    end

    subgraph "Data Layer"
        RDBMS["Primary RDBMS"]:::database
        Mongo["MongoDB (Optional)"]:::database
    end

    subgraph "External Services"
        LDAP["LDAP/OAuth Provider"]:::external
        SMTP["SMTP Server"]:::external
        S3["S3 (Optional)"]:::external
        Burp["Burp Suite Extension"]:::external
    end

    Browser["Browser Client"]:::frontend

    Browser -->|HTTP/HTTPS| JSP
    JSP -->|render| WebContainer
    WebContainer -->|dispatch| MVC
    WebContainer -->|dispatch| REST
    WebContainer -->|invoke| Services
    MVC -->|use| Services
    REST -->|use| Services
    Services -->|CRUD| DAO
    DAO -->|JDBC| RDBMS
    Services -->|Mongo driver| Mongo
    Services -->|load plugins| Extender
    Services -->|queue tasks| Tasks
    Tasks -->|async email/report| SMTP
    Reporting -->|generate DOCX| WebContainer
    Reporting -->|templates| S3
    WebContainer -->|auth| LDAP
    Burp -->|HTTPS REST| REST

    click Dockerfile "https://github.com/factionsecurity/faction/tree/main/Dockerfile"
    click DockerCompose "https://github.com/factionsecurity/faction/blob/main/docker-compose.yml"
    click DockerComposeDev "https://github.com/factionsecurity/faction/blob/main/docker-compose-dev.yml"
    click Entrypoint "https://github.com/factionsecurity/faction/blob/main/entrypoint.sh"
    click POM "https://github.com/factionsecurity/faction/blob/main/pom.xml"
    click JSP "https://github.com/factionsecurity/faction/blob/main/WebContent/index.jsp"
    click JSPDir "https://github.com/factionsecurity/faction/tree/main/WebContent/WEB-INF/jsp/"
    click Dist "https://github.com/factionsecurity/faction/tree/main/WebContent/dist/"
    click Bootstrap "https://github.com/factionsecurity/faction/tree/main/WebContent/bootstrap/"
    click Plugins "https://github.com/factionsecurity/faction/tree/main/WebContent/plugins/"
    click WebpackProd "https://github.com/factionsecurity/faction/blob/main/WebContent/webpack.config.js"
    click WebpackDev "https://github.com/factionsecurity/faction/blob/main/WebContent/webpack.config-dev.js"
    click MVC "https://github.com/factionsecurity/faction/tree/main/src/com/fuse/actions/"
    click REST "https://github.com/factionsecurity/faction/tree/main/src/com/fuse/api/"
    click Services "https://github.com/factionsecurity/faction/tree/main/src/com/fuse/utils/"
    click DAO "https://github.com/factionsecurity/faction/tree/main/src/com/fuse/dao/"
    click Extender "https://github.com/factionsecurity/faction/tree/main/src/com/fuse/extenderapi/"
    click Reporting "https://github.com/factionsecurity/faction/tree/main/src/com/fuse/reporting/"
    click Tasks "https://github.com/factionsecurity/faction/tree/main/src/com/fuse/tasks/"
    click Servlets "https://github.com/factionsecurity/faction/tree/main/src/com/fuse/servlets/"
    click Taglib "https://github.com/factionsecurity/faction/tree/main/src/com/fuse/taglib/"
    click RDBMS "https://github.com/factionsecurity/faction/blob/main/src/META-INF/persistence.xml"

    classDef frontend fill:#D0E8FF,stroke:#66A3FF,color:#000
    classDef backend fill:#DFF5D0,stroke:#66CC33,color:#000
    classDef database fill:#FFE8D0,stroke:#FF9933,color:#000
    classDef external fill:#E8D0FF,stroke:#A366FF,color:#000
    classDef docker fill:#F0F0F0,stroke:#999999,color:#000
```
