# hcl-tech-software/altoroj architecture

> Architecture diagram of the GitHub repository hcl-tech-software/altoroj, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hcl-tech-software/altoroj
- Repository: https://github.com/hcl-tech-software/altoroj

## Overview

##### Project Type & Purpose
- AltoroJ is a full-stack J2EE web application with a focus on banking functionality and security vulnerability demonstration.
- It uses standard Java, JSP, Servlets, and Filters as its core technology – making it ideal for illustrating both web application structure and security issues.

##### File Structure
- Notice that the top-level directories include configuration/IDE files (.settings, .project), a WebContent folder (housing JSP pages, static assets, and WEB-INF configurations), and a src folder (containing Java source code).
- WebContent contains directories for JSP pages (e.g., bank, admin), static content like images and CSS, and the WEB-INF folder that holds configuration files (web.xml, app.properties) and libraries.
- The src directory further divides into packages (com.ibm.security.appscan.altoromutual) with sub-packages for:
– API endpoints (AccountAPI, AdminAPI, etc.)
– Filters (e.g., AuthFilter, AdminFilter, ApiAuthFilter)
– Servlets to handle user actions (LoginServlet, TransferServlet, etc.)
– Model classes (Account, Feedback, Transaction, User)
– Utility classes (DBUtil, OperationsUtil, ServletUtil)
- A separate directory (“swagger”) within WebContent documents and exposes the REST API via Swagger UI.

##### Key Components
a. Web Client / Browser:
– Represents users accessing the application through their browsers.
– Includes both standard web navigation (JSP pages & forms) and queries via the REST API (accessed through Swagger).

b. Application Server (Tomcat 7):
– Deployed as a WAR package containing the WebContent directory and the Java code compiled from src.
– Divided into multiple layers:
- Web Layer: JSP pages, static assets (CSS, images, JSPF includes) for the look and feel.
- Controller Layer: Servlets that process requests, route actions and handle both standard interactions and REST API calls.
- Filter & Listener Layer: Security filters (AuthFilter, ApiAuthFilter, AdminFilter) that check and control access, plus listeners (StartupListener) for initialization events.

c. Business Logic / Model Layer:
– Represented by the classes in the model package (Account, Feedback, Transaction, User) that encapsulate core business data.
– The API classes in the “api” sub-package serve as endpoints exposing business functionality, typically consumed by REST API calls.

d. Database (Apache Derby):
– The application uses Apache Derby as the SQL database.
– DBUtil (and possibly other utility classes) are used to handle connectivity and basic CRUD operations on the database.
– Note that the database is auto-initialized on the first successful login and is persisted in the “altoro” folder under the user’s home directory.

e. REST API Component:
– The “swagger” directory in WebContent provides clients a way to interact with the REST services defined in the API package.

##### Relationships and Interactions
- Inside the Application Server, illustrate the flow:
1. Incoming HTTP requests are intercepted by Filters (authentication/authorization).
2. Requests are then delegated to the appropriate Servlets or API controllers.
3. Servlets interact with utility classes and the Model layer to execute business logic.
4. For data persistence, a connection is made to the Apache Derby database via DBUtil.
- Role of the Listener (StartupListener) which initializes configuration or resources during server start-up.

##### Architectural Patterns and Design Principles
- MVC Pattern:
– View: JSP pages and static content.
– Controller: Servlets and API classes managing request/response cycles.
– Model: Java classes representing data and business logic.
- Security Considerations:
– The presence of Filters indicates pre-processing for security checks (both for normal web sessions and API calls).
- Separation of Concerns:
– Clear directory separation between presentation (WebContent) and business logic (src).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        A("Web Client (Browser)"):::client
    end

    subgraph "Application Server (Tomcat 7)"
        subgraph "Web Layer"
            B("JSP Views"):::jweb
            subgraph "JSP Details"
                B1("Bank Pages"):::jweb
                B2("Admin Pages"):::jweb
                B3("Index Page"):::jweb
                B4("Login Page"):::jweb
            end
        end
        subgraph "API Documentation"
            BA("Swagger UI"):::swagger
        end
        subgraph "Filter & Listener Layer"
            C("Security Filters"):::filter
            D("Startup Listener"):::listener
        end
        subgraph "Controller Layer"
            E("Servlets"):::servlet
            F("REST API Endpoints"):::api
        end
        subgraph "Business / Model Layer"
            G("Business Logic (Model)"):::model
        end
        subgraph "Utility Layer"
            H("DB Connectivity Utility"):::util
        end
    end

    subgraph "Database"
        I(("Apache Derby Database")):::database
    end

    A -->|"HTTP"| B
    A -->|"HTTP"| BA
    B -->|"filter"| C
    BA -->|"filter"| C
    C -->|"delegate"| E
    C -->|"delegate"| F
    D ---|"init"| E
    D ---|"init"| F
    E -->|"process"| G
    F -->|"process"| G
    G -->|"uses"| H
    H -->|"CRUD"| I

    click B "https://github.com/hcl-tech-software/altoroj/tree/AltoroJ-3.2/WebContent"
    click B1 "https://github.com/hcl-tech-software/altoroj/tree/AltoroJ-3.2/WebContent/bank"
    click B2 "https://github.com/hcl-tech-software/altoroj/tree/AltoroJ-3.2/WebContent/admin"
    click B3 "https://github.com/hcl-tech-software/altoroj/blob/AltoroJ-3.2/WebContent/index.jsp"
    click B4 "https://github.com/hcl-tech-software/altoroj/blob/AltoroJ-3.2/WebContent/login.jsp"
    click BA "https://github.com/hcl-tech-software/altoroj/tree/AltoroJ-3.2/WebContent/swagger"
    click E "https://github.com/hcl-tech-software/altoroj/tree/AltoroJ-3.2/src/com/ibm/security/appscan/altoromutual/servlet"
    click F "https://github.com/hcl-tech-software/altoroj/tree/AltoroJ-3.2/src/com/ibm/security/appscan/altoromutual/api"
    click C "https://github.com/hcl-tech-software/altoroj/tree/AltoroJ-3.2/src/com/ibm/security/appscan/altoromutual/filter"
    click D "https://github.com/hcl-tech-software/altoroj/blob/AltoroJ-3.2/src/com/ibm/security/appscan/altoromutual/listener/StartupListener.java"
    click G "https://github.com/hcl-tech-software/altoroj/tree/AltoroJ-3.2/src/com/ibm/security/appscan/altoromutual/model"
    click H "https://github.com/hcl-tech-software/altoroj/blob/AltoroJ-3.2/src/com/ibm/security/appscan/altoromutual/util/DBUtil.java"

    classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef jweb fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef swagger fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef filter fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef listener fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef servlet fill:#d9d2e9,stroke:#333,stroke-width:2px;
    classDef api fill:#ffe6cc,stroke:#333,stroke-width:2px;
    classDef model fill:#e1f7d5,stroke:#333,stroke-width:2px;
    classDef util fill:#f7e1d5,stroke:#333,stroke-width:2px;
    classDef database fill:#f2d7d5,stroke:#333,stroke-width:2px;
```
