# bujiio/buji-pac4j architecture

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

- Interactive diagram: https://gitdiagram.com/bujiio/buji-pac4j
- Repository: https://github.com/bujiio/buji-pac4j

## Overview

##### Project type and purpose
- This is a Java-based **security bridge library** (buji-pac4j) that integrates the pac4j security engine into Apache Shiro.
- Its sole purpose is to adapt pac4j’s authentication/profile mechanism into Shiro’s subject/realm model, allowing legacy Shiro applications to leverage pac4j clients without full migration.

##### File structure
- Top‐level artifacts:
- pom.xml – Maven build, dependencies on pac4j & Shiro.
- src/main/java/io/buji/pac4j – core adapter code.
- src/main/resources/buji-pac4j-default.ini – default Shiro INI config for automatic installation.
- META-INF/services/org.apache.shiro.web.env.WebEnvironment – service loader entry to hook into Shiro.
- Key packages:
- context – ShiroSessionStore, Pac4jIniEnvironment
- realm – Pac4jRealm (Shiro Realm implementation)
- subject – Pac4jPrincipal, Pac4jSubjectFactory
- token – Pac4jToken
- util – ShiroHelper
- You also have adapter code under org.pac4j.framework/adapter (FrameworkAdapterImpl).

##### README for additional insights
- Confirms: “bridge only” for Shiro v2.x + pac4j v6.
- Usage is plug-and-play: drop the JAR, add to classpath, configure via INI, then configure your pac4j clients/filters in Shiro.

##### Details
- Package names (e.g., io.buji.pac4j.realm.Pac4jRealm) next to each bridge component.
- Default INI file loading (buji-pac4j-default.ini) feeding into WebEnvironment.
- SessionStore delegation: Pac4jSessionStore → ShiroSession.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    App["Web Application"]:::external
    App -->|"HTTP Request"| ShiroFilterChain

    %% Shiro Core Layer
    ShiroFilterChain["Shiro FilterChain"]:::shiro
    ShiroFilterChain -->|"intercepts"| BujiFilter

    %% buji-pac4j Adapter Layer
    subgraph "buji-pac4j Bridge"
        BujiFilter["buji-pac4j Filter\n(io.buji.pac4j.context)"]:::adapter
        Pac4jRealm["io.buji.pac4j.realm.Pac4jRealm"]:::adapter
        ShiroSessionStore["io.buji.pac4j.context.ShioSessionStore"]:::adapter
        Pac4jSubjectFactory["io.buji.pac4j.subject.Pac4jSubjectFactory"]:::adapter
        Pac4jPrincipal["io.buji.pac4j.subject.Pac4jPrincipal"]:::adapter
        Pac4jToken["io.buji.pac4j.token.Pac4jToken"]:::adapter
        Pac4jIniEnv["io.buji.pac4j.env.Pac4jIniEnvironment"]:::adapter
        ShiroHelper["io.buji.pac4j.util.ShiroHelper"]:::adapter
        FrameworkAdapter["org.pac4j.framework.adapter.FrameworkAdapterImpl"]:::adapter
    end

    BujiFilter -->|"delegates to"| Pac4jClient
    Pac4jClient["Pac4j Clients\n(io.pac4j.client)"]:::engine
    Pac4jClient -->|"auth flow"| ExternalIDP

    %% External Identity Providers
    ExternalIDP["External Identity Provider\n(OAuth/SAML/etc.)"]:::external
    ExternalIDP -->|"UserProfile"| BujiFilter

    BujiFilter -->|"wraps to Pac4jToken & Pac4jPrincipal"| Pac4jToken
    Pac4jToken -->|"authenticates"| Pac4jRealm
    Pac4jRealm -->|"creates Subject"| Subject
    ShiroSessionStore -->|"delegates session calls to"| ShiroSession

    Subject["Shiro Subject\n(SecurityManager)"]:::shiro
    ShiroSession["Shiro Session"]:::shiro

    %% Configuration & ServiceLoader
    IniFile["buji-pac4j-default.ini"]:::config
    ServiceLoader["ServiceLoader SPI\n(META-INF/services)"]:::config
    IniFile --> Pac4jIniEnv
    ServiceLoader --> Pac4jIniEnv
    Pac4jIniEnv --> ShiroFilterChain

    %% Click Events
    click ShiroSessionStore "https://github.com/bujiio/buji-pac4j/blob/master/src/main/java/io/buji/pac4j/context/ShiroSessionStore.java"
    click Pac4jIniEnv "https://github.com/bujiio/buji-pac4j/blob/master/src/main/java/io/buji/pac4j/env/Pac4jIniEnvironment.java"
    click Pac4jRealm "https://github.com/bujiio/buji-pac4j/blob/master/src/main/java/io/buji/pac4j/realm/Pac4jRealm.java"
    click Pac4jPrincipal "https://github.com/bujiio/buji-pac4j/blob/master/src/main/java/io/buji/pac4j/subject/Pac4jPrincipal.java"
    click Pac4jSubjectFactory "https://github.com/bujiio/buji-pac4j/blob/master/src/main/java/io/buji/pac4j/subject/Pac4jSubjectFactory.java"
    click Pac4jToken "https://github.com/bujiio/buji-pac4j/blob/master/src/main/java/io/buji/pac4j/token/Pac4jToken.java"
    click ShiroHelper "https://github.com/bujiio/buji-pac4j/blob/master/src/main/java/io/buji/pac4j/util/ShiroHelper.java"
    click FrameworkAdapter "https://github.com/bujiio/buji-pac4j/blob/master/src/main/java/org/pac4j/framework/adapter/FrameworkAdapterImpl.java"
    click IniFile "https://github.com/bujiio/buji-pac4j/blob/master/src/main/resources/buji-pac4j-default.ini"
    click ServiceLoader "https://github.com/bujiio/buji-pac4j/blob/master/src/main/resources/META-INF/services/org.apache.shiro.web.env.WebEnvironment"

    %% Styling
    classDef shiro fill:#cce5ff,stroke:#005cbf,color:#005cbf
    classDef adapter fill:#d4edda,stroke:#155724,color:#155724
    classDef engine fill:#ffe5b4,stroke:#cc7a00,color:#cc7a00
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef config fill:#f8d7da,stroke:#721c24,color:#721c24
```
