# fenixedu/bennu architecture

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

- Interactive diagram: https://gitdiagram.com/fenixedu/bennu
- Repository: https://github.com/fenixedu/bennu

## Overview

##### Project type and purpose
- This is a modular Java web‐application framework (monorepo) called “Bennu” built on top of the Fenix-Framework.
- It provides foundational services (authentication, REST API, job scheduling, file storage, search indexing, theming) and ready‐to‐use frontend modules (admin UI, portal, toolkit, OAuth/CAS/SAML flows).

##### File structure
- Top‐level POM orchestrates multiple Maven submodules:
- bennu-core: core bootstrap, filters, Jersey REST endpoints, domain model.
- bennu-io: file storage API and adapters (local FS, Drive API).
- bennu-scheduler: job/task scheduling runtime and REST monitoring API.
- bennu-search: domain indexing services.
- bennu-oauth, bennu-cas-client, bennu-saml-client: authentication flows and servlet filters.
- bennu-spring: Spring-MVC integration wrappers.
- bennu-admin, bennu-portal, default-theme, bennu-toolkit: frontend webapps (JSP, HTML templates, JS).
- bennu-maven-plugin: build‐time code generation.
- bennu-test: integration/unit test cases.
- Each module uses DML mapping files, Java packages under org.fenixedu.bennu.* and web fragments (META-INF/web-fragment.xml) to auto-register servlet components.

##### README for additional insights
- It states Bennu’s goal: build modular Java web apps without reinventing authentication, scheduling, user management.

a. Main components
- Web Container (e.g., Tomcat) hosting the unified WAR
- Core Module (bennu-core)
- Submodules:
- Authentication Clients (CAS, OAuth, SAML)
- File Storage Service (bennu-io)
- Scheduler Service (bennu-scheduler)
- Search Index Service (bennu-search)
- Spring Integration (bennu-spring)
- Maven Plugin (bennu-maven-plugin)
- Frontend Applications (bennu-admin, portal, default-theme, toolkit)
- Database (backing domain model persisted by FenixFramework)
- External Services: CAS Server, OAuth Provider, SAML IdP, Drive API

b. Relationships and interactions
- Clients (browser) → Static assets & JS from frontend modules.
- Frontend modules → REST/API endpoints in core and submodules.
- Core Module registers Jersey application and servlet filters.
- Authentication filters redirect to external CAS/OAuth/SAML providers and ingest callbacks.
- Scheduler polls domain tasks and executes them in background threads.
- FileStorage API adapters write/read to DB or external Drive API.
- Search module reacts to domain object events (Signal EventBus) to update indices.
- Maven plugin runs at build time to generate DML/domain scaffolding.

c. Architectural patterns / design principles
- Modular Monolith using Servlet 3.x web fragments and SPI for auto-registration.
- Plugin architecture: each feature is a module that plugs into the core.
- RESTful services with Jersey (JAX-RS).
- Domain events via Signal EventBus for decoupling.
- DML mapping defines domain model; FenixFramework ORM for persistence.
- Background scheduling thread pool.
- Spring Adapter module exposes MVC controllers.

d. Key technologies / frameworks
- Java 8+, Maven multi-module
- Servlet 3.x, web fragments
- Jersey (JAX-RS)
- FenixFramework (DML + ORM)
- Jackson/Gson for JSON adapters
- Spring MVC (optional)
- JavaScript/CSS libraries in frontend (CodeMirror, Fancytree, Moment.js)

##### Essential elements
- Module names and their responsibilities
- Data flows (HTTP calls, DB reads/writes, event publications)
- Initialization paths (ServletContainerInitializer → module bootstrapper)
- Key REST resources and filters
- Scheduling and task execution flow
- File storage adapters and chosen storage backend

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Browser(("Browser")):::external

    %% Frontend Modules
    subgraph "Frontend Modules"
        AdminUI["Admin UI<br/>(bennu-admin)"]:::frontend
        PortalUI["Portal UI<br/>(bennu-portal)"]:::frontend
        ThemeUI["Default Theme<br/>(default-theme)"]:::frontend
        ToolkitUI["Toolkit<br/>(bennu-toolkit)"]:::frontend
    end

    %% Backend Modules
    subgraph "Core & Integration"
        Core["Core Module<br/>(bennu-core)"]:::backend
        SpringMod["Spring Integration<br/>(bennu-spring)"]:::backend
        MavenPlugin["Maven Plugin<br/>(bennu-maven-plugin)"]:::backend
        TestMod["Tests<br/>(bennu-test)"]:::backend
    end

    %% Services Modules
    subgraph "Service Modules"
        FileStorageMod["File Storage Service<br/>(bennu-io)"]:::backend
        SchedulerMod["Scheduler Service<br/>(bennu-scheduler)"]:::backend
        SearchMod["Search Index Service<br/>(bennu-search)"]:::backend
    end

    %% Authentication Modules
    subgraph "Authentication Clients"
        OAuthMod["OAuth Client<br/>(bennu-oauth)"]:::backend
        CASMod["CAS Client<br/>(bennu-cas-client)"]:::backend
        SAMLMod["SAML Client<br/>(bennu-saml-client)"]:::backend
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Database[(Database)]:::infra
        EventBus[(EventBus)]:::infra
    end

    %% External Services
    subgraph "External Providers"
        CASSrv["CAS Server"]:::external
        OAuthProv["OAuth Provider"]:::external
        SAMLIdP["SAML IdP"]:::external
        DriveAPI["Drive API"]:::external
    end

    %% Top-level aggregator
    POM["pom.xml"]:::backend

    %% Relationships
    Browser --> AdminUI
    Browser --> PortalUI
    Browser --> ThemeUI
    Browser --> ToolkitUI

    AdminUI -->|REST calls| Core
    PortalUI -->|REST calls| Core
    ToolkitUI -->|REST calls| Core

    Core --> Database
    SpringMod --> Core
    Core -->|publishes events| EventBus
    EventBus -->|consumed by| SearchMod
    SearchMod --> Database

    SchedulerMod -->|uses domain model| Core
    SchedulerMod --> Database

    FileStorageMod --> Database
    FileStorageMod -->|optional| DriveAPI

    Core --> OAuthMod
    Core --> CASMod
    Core --> SAMLMod

    OAuthMod --> OAuthProv
    CASMod --> CASSrv
    SAMLMod --> SAMLIdP

    MavenPlugin -.-> Core
    TestMod --> Core

    POM --> Core
    POM --> FileStorageMod
    POM --> SchedulerMod
    POM --> SearchMod
    POM --> OAuthMod
    POM --> CASMod
    POM --> SAMLMod
    POM --> SpringMod
    POM --> MavenPlugin
    POM --> TestMod
    POM --> AdminUI
    POM --> PortalUI
    POM --> ThemeUI
    POM --> ToolkitUI

    %% Click events
    click Core "https://github.com/fenixedu/bennu/tree/master/bennu-core/"
    click FileStorageMod "https://github.com/fenixedu/bennu/tree/master/bennu-io/"
    click SchedulerMod "https://github.com/fenixedu/bennu/tree/master/bennu-scheduler/"
    click SearchMod "https://github.com/fenixedu/bennu/tree/master/bennu-search/"
    click OAuthMod "https://github.com/fenixedu/bennu/tree/master/bennu-oauth/"
    click CASMod "https://github.com/fenixedu/bennu/tree/master/bennu-cas-client/"
    click SAMLMod "https://github.com/fenixedu/bennu/tree/master/bennu-saml-client/"
    click SpringMod "https://github.com/fenixedu/bennu/tree/master/bennu-spring/"
    click MavenPlugin "https://github.com/fenixedu/bennu/tree/master/bennu-maven-plugin/"
    click TestMod "https://github.com/fenixedu/bennu/tree/master/bennu-test/"
    click AdminUI "https://github.com/fenixedu/bennu/tree/master/bennu-admin/"
    click PortalUI "https://github.com/fenixedu/bennu/tree/master/bennu-portal/"
    click ThemeUI "https://github.com/fenixedu/bennu/tree/master/default-theme/"
    click ToolkitUI "https://github.com/fenixedu/bennu/tree/master/bennu-toolkit/"
    click POM "https://github.com/fenixedu/bennu/blob/master/pom.xml"

    %% Styles
    classDef backend fill:#cce4ff,stroke:#333,stroke-width:1px
    classDef frontend fill:#d5f5e3,stroke:#333,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef infra fill:#e0e0e0,stroke:#333,stroke-width:1px
```
