# julioarruda/vulnado architecture

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

- Interactive diagram: https://gitdiagram.com/julioarruda/vulnado
- Repository: https://github.com/julioarruda/vulnado

## Overview

##### Main Components
- Web Frontend: Represented in the "client" directory. It includes HTML, CSS, and JavaScript files. This component is externally accessible, forming the publicly facing site.
- API/Backend Server: Found in the "src/main/java/com/scalesec/vulnado" folder. This is the core of the Java application and includes controllers for handling login, comments, links, and other endpoints.
- Database (and possibly other data stores): The Postgres connection (see Postgres.java) suggests that a database is being used, although the docker-compose file might be defining the actual service.
- Internal Site: Located in the "internal_site" directory. This component is designed to be accessible only on the internal network, reflecting a separate tier for sensitive operations or administrative interfaces.
- Vulnerability Exercises and Assets: The "exercises" directory contains markdown files that document specific vulnerabilities and come with supporting assets (e.g., XML files). There is also a "reverse_shell" directory that can be viewed as a specialized exercise demonstrating Remote Code Execution.

##### Component Relationships and Data Flows
- The publicly available "client" connects to the "API/Backend Server" using HTTP/HTTPS over specific ports (e.g., 8080 for API verification as mentioned in the README).
- The backend service interacts with the Database for persistent storage (e.g., user data, comments, etc.) as hinted by the Postgres-related files.
- The docker-compose defines a network that separates publicly accessible components (web server in "client") from internal services (internal_site and database).
- Exercises, including reverse shell demonstrations, connect logically to the system as learning modules, illustrating how vulnerabilities in interactions or configurations can be exploited.
- The CI/CD system (GitHub Actions) automates building (using Maven and docker-compose) and testing. It should be depicted interacting with the source code repository and triggering container builds.

##### Architectural Patterns and Design Principles
- Multi-tier Architecture: The system is divided into distinct tiers (public web server, application/API, internal services, and the database).
- Containerization: Docker and docker-compose play a significant role, encapsulating each service (client, internal_site, backend) into its own container, with defined inter-container networking.
- Microservices/Modularity (to a degree): Although the backend appears monolithic in the Java project, clear modular separations (different controllers for various functionalities) are visible.
- DevOps Practice: Integration with CI (via GitHub Actions) is part of the architecture which ensures the automation of tests and builds.

##### Technologies and Frameworks
- Java (Spring Boot or similar, based on the structure in src/main/java/com/scalesec/vulnado)
- Maven (build automation using pom.xml and mvnw)
- Docker and docker-compose for container orchestration
- GitHub Actions for continuous integration
- HTML, CSS, JavaScript for the client-side code

##### Elements
- From the Client to the API Server (HTTP requests/responses).
- From the API Server to the Database.
- Communication among containers as defined by docker-compose.
- CI/CD interactions that trigger builds and tests.
- Optionally, include annotations for vulnerabilities or exercises (like SQL injection, XSS, etc.) to denote the learning/intentional vulnerability aspects.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Public Network
    subgraph "Public Network"
        direction TB
        CLIENT["Client Web UI"]:::frontend
        API["API Server"]:::backend
    end

    CLIENT -->|"HTTP/HTTPS"| API
    API -->|"DB Queries"| DB["Database"]:::database

    %% Internal Network for sensitive operations
    subgraph "Internal Network"
        direction TB
        INT_SITE["Internal Site"]:::internal
    end

    API ---|"AdminAccess"| INT_SITE

    %% Vulnerability Exercises
    subgraph "Learning Modules"
        direction TB
        EX["Vulnerability Exercises"]:::vulnerability
        RS["Reverse Shell Demo"]:::vulnerability
    end

    API ---|"ExemplifiesVuln"| EX
    EX -->|"Includes"| RS

    %% CI/CD Pipeline
    CI["CI/CD Pipeline"]:::cicd
    CI -->|"Build&Test"| API
    CI -->|"DeploysTo"| CLIENT

    %% Click Events
    click CLIENT "https://github.com/julioarruda/vulnado/tree/master/client/"
    click API "https://github.com/julioarruda/vulnado/tree/master/src/main/java/com/scalesec/vulnado/"
    click DB "https://github.com/julioarruda/vulnado/blob/master/src/main/java/com/scalesec/vulnado/Postgres.java"
    click INT_SITE "https://github.com/julioarruda/vulnado/tree/master/internal_site/"
    click EX "https://github.com/julioarruda/vulnado/tree/master/exercises/"
    click RS "https://github.com/julioarruda/vulnado/tree/master/reverse_shell/"
    click CI "https://github.com/julioarruda/vulnado/tree/master/.github/workflows/"

    %% Styles
    classDef frontend fill:#ffebcd,stroke:#d2691e,stroke-width:2px;
    classDef backend fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef internal fill:#e6e6fa,stroke:#4b0082,stroke-width:2px;
    classDef database fill:#98fb98,stroke:#228b22,stroke-width:2px;
    classDef vulnerability fill:#ffe4e1,stroke:#ff1493,stroke-width:2px;
    classDef cicd fill:#fffacd,stroke:#daa520,stroke-width:2px;
```
