# litesaml/lightsaml architecture

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

- Interactive diagram: https://gitdiagram.com/litesaml/lightsaml
- Repository: https://github.com/litesaml/lightsaml

## Overview

##### Project type and purpose
- This is an open-source PHP library (“Lite Saml”) implementing core SAML 2.0 functionality: data models, XML serialization/deserialization, XML-security (sign/verify), HTTP bindings, message building, validation, and a pluggable execution pipeline. It’s meant to be embedded in Service Providers or Identity Providers, not a standalone web app.

##### Main components
a. Binding Layer
- HttpRedirectBinding, HttpPostBinding, SamlPostResponse
- Responsibilities: map HTTP requests/responses ↔ SAML XML payloads
b. Data Model Layer
- Model classes under src/Model (Assertion, Protocol, Metadata, XmlDSig)
- Holds the in-memory representation of SAML messages
c. Serialization / Deserialization
- XmlDSig readers/writers, serialization contexts → XML↔PHP objects
d. Action Pipeline Engine
- ActionInterface, CompositeAction, ActionLogWrapper, DispatchEventAction
- Chain-of-Responsibility for validating, transforming, dispatching messages
e. Profile Builders & Contexts
- Builder/* (ActionBuilder, ProfileBuilder, ContextBuilders)
- ProfileContext, AssertionContext, EndpointContext
- High-level entry points for SP/IdP use cases (SSO, SLO)
f. Credentials, Providers, Resolvers, Store Modules
- CredentialInterface, X509Credential; Providers fetch keys/metadata;
Resolver implementations pick the right credential/endpoint;
Store interfaces for persistence of metadata, state, trust options, request states
g. DI Container Bridge
- Bridge/Pimple Container classes, Factory providers → sets up all services via Pimple
h. Error & Event System
- LightSaml*Exception classes, Event classes (MessageReceived, MessageSent)

##### Component relationships & data flow
- Incoming HTTP Request → Binding Layer (HttpPost/Redirect)
- Binding outputs raw XML → Deserialization Context → Data Model objects
- Model enters Action Pipeline
- each Action (signature, issuer, time, replay-attack checks)
- Actions may call Providers/Resolvers/Stores
- On success, DispatchEventAction emits MessageReceived
- Consumer code uses Profile Context or Builder to produce outbound message
- Builder composes Action pipeline for outbound, calls SignMessageAction, SaveRequestStateAction, etc.
- Pipeline ends in SendMessageAction → Binding → HTTP Response/Redirect

##### Architectural patterns & design principles
- Chain of Responsibility: Action pipeline (ActionInterface, CompositeAction)
- Builder & Factory: ProfileBuilder, ActionBuilder, CredentialResolverFactory
- Strategy/Resolver: pluggable CredentialResolver, EndpointResolver
- Dependency Injection: Pimple bridge for wiring modules
- Composite: CompositeAction, CompositeResolver, CompositeTrustOptionsStore

##### Technologies & frameworks
- PHP 8.1, Composer autoload
- Pimple for DI
- PHPUnit for tests
- phpstan, phpcs, rector for static analysis & code style

##### Final checklist
- Clear component labels and namespaces
- External integration points (HTTP layer, user code that invokes ProfileBuilder)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External HTTP
    HTTP_REQ[/"HTTP Request"/]:::external
    HTTP_RES["HTTP Response"]:::external

    %% Binding & Serialization
    subgraph "Binding & Serialization"
        direction TB
        HttpRedirectBinding["HttpRedirectBinding"]:::binding
        HttpPostBinding["HttpPostBinding"]:::binding
        SamlPostResponse["SamlPostResponse"]:::binding
        AbstractBinding["AbstractBinding"]:::binding
        BindingFactory["BindingFactory"]:::binding
        BindingFactoryInterface["BindingFactoryInterface"]:::binding
        DeserializationContext["DeserializationContext"]:::binding
        SerializationContext["SerializationContext"]:::binding
    end

    %% Data Model Layer
    subgraph "Data Model Layer"
        direction TB
        AssertionModel["Assertion"]:::datamodel
        EncryptedAssertionReader["EncryptedAssertionReader"]:::datamodel
        EncryptedAssertionWriter["EncryptedAssertionWriter"]:::datamodel
        AuthnRequest["AuthnRequest"]:::datamodel
        LogoutRequest["LogoutRequest"]:::datamodel
        EntityDescriptor["EntityDescriptor"]:::datamodel
        Signature["Signature"]:::datamodel
    end

    %% Action Pipeline Engine
    subgraph "Action Pipeline Engine"
        direction TB
        ActionInterface["ActionInterface"]:::action
        CompositeAction["CompositeAction"]:::action
        ActionLogWrapper["ActionLogWrapper"]:::action
        DispatchEventAction["DispatchEventAction"]:::action
    end

    %% Profile Builders & Contexts
    subgraph "Profile Builders & Contexts"
        direction TB
        AbstractProfileBuilder["AbstractProfileBuilder"]:::profile
        ProfileContext["ProfileContext"]:::profile
        AssertionContext["AssertionContext"]:::profile
        EndpointContext["EndpointContext"]:::profile
    end

    %% Providers / Resolvers / Stores
    subgraph "Providers/Resolvers/Stores"
        direction TB
        X509CredentialFileProvider["X509CredentialFileProvider"]:::provider
        CredentialResolverInterface["CredentialResolverInterface"]:::provider
        CompositeCredentialStore["CompositeCredentialStore"]:::provider
    end

    %% DI Container Bridge
    subgraph "DI Container Bridge"
        direction TB
        BuildContainer["BuildContainer"]:::di
    end

    %% Error & Event System
    subgraph "Error & Event System"
        direction TB
        LightSamlException["LightSamlException"]:::error
        MessageReceived["MessageReceived"]:::error
        MessageSent["MessageSent"]:::error
    end

    %% Data Flow
    HTTP_REQ -->|"incoming request"| HttpPostBinding
    HTTP_REQ -->|"incoming request"| HttpRedirectBinding

    HttpPostBinding -->|"extract XML"| DeserializationContext
    HttpRedirectBinding -->|"extract XML"| DeserializationContext

    DeserializationContext -->|"build objects"| AssertionModel
    DeserializationContext --> EncryptedAssertionReader
    AssertionModel --> EncryptedAssertionWriter

    AssertionModel --> AuthnRequest
    AssertionModel --> LogoutRequest
    AssertionModel --> EntityDescriptor
    AssertionModel --> Signature

    %% Model enters pipeline
    Signature --> CompositeAction
    AuthnRequest --> CompositeAction
    LogoutRequest --> CompositeAction
    CompositeAction -->|"Chain of Responsibility"| ActionInterface
    CompositeAction --> ActionLogWrapper
    CompositeAction --> DispatchEventAction

    %% Pipeline uses providers/resolvers/stores
    CompositeAction --> X509CredentialFileProvider
    CompositeAction --> CredentialResolverInterface
    CompositeAction --> CompositeCredentialStore

    DispatchEventAction --> MessageReceived

    %% Consumer uses profile builder
    MessageReceived --> AbstractProfileBuilder
    AbstractProfileBuilder --> ProfileContext
    ProfileContext --> AssertionContext
    ProfileContext --> EndpointContext

    %% Outbound pipeline
    AbstractProfileBuilder --> CompositeAction
    CompositeAction -->|"build outbound"| SerializationContext
    SerializationContext --> SamlPostResponse
    SerializationContext --> HttpPostBinding
    SerializationContext --> HttpRedirectBinding
    HttpPostBinding --> HTTP_RES
    HttpRedirectBinding --> HTTP_RES
    SamlPostResponse --> HTTP_RES

    %% DI wiring
    BuildContainer --> CompositeAction
    BuildContainer --> AbstractProfileBuilder
    BuildContainer --> X509CredentialFileProvider
    BuildContainer --> CredentialResolverInterface
    BuildContainer --> CompositeCredentialStore

    %% Errors & Events
    CompositeAction --> LightSamlException
    DispatchEventAction --> MessageSent

    %% Click Events
    click HttpRedirectBinding "https://github.com/litesaml/lightsaml/blob/master/src/Binding/HttpRedirectBinding.php"
    click HttpPostBinding "https://github.com/litesaml/lightsaml/blob/master/src/Binding/HttpPostBinding.php"
    click SamlPostResponse "https://github.com/litesaml/lightsaml/blob/master/src/Binding/SamlPostResponse.php"
    click AbstractBinding "https://github.com/litesaml/lightsaml/blob/master/src/Binding/AbstractBinding.php"
    click BindingFactory "https://github.com/litesaml/lightsaml/blob/master/src/Binding/BindingFactory.php"
    click BindingFactoryInterface "https://github.com/litesaml/lightsaml/blob/master/src/Binding/BindingFactoryInterface.php"
    click AssertionModel "https://github.com/litesaml/lightsaml/blob/master/src/Model/Assertion/Assertion.php"
    click EncryptedAssertionReader "https://github.com/litesaml/lightsaml/blob/master/src/Model/Assertion/EncryptedAssertionReader.php"
    click EncryptedAssertionWriter "https://github.com/litesaml/lightsaml/blob/master/src/Model/Assertion/EncryptedAssertionWriter.php"
    click AuthnRequest "https://github.com/litesaml/lightsaml/blob/master/src/Model/Protocol/AuthnRequest.php"
    click LogoutRequest "https://github.com/litesaml/lightsaml/blob/master/src/Model/Protocol/LogoutRequest.php"
    click EntityDescriptor "https://github.com/litesaml/lightsaml/blob/master/src/Model/Metadata/EntityDescriptor.php"
    click Signature "https://github.com/litesaml/lightsaml/blob/master/src/Model/XmlDSig/Signature.php"
    click DeserializationContext "https://github.com/litesaml/lightsaml/blob/master/src/Model/Context/DeserializationContext.php"
    click SerializationContext "https://github.com/litesaml/lightsaml/blob/master/src/Model/Context/SerializationContext.php"
    click ActionInterface "https://github.com/litesaml/lightsaml/blob/master/src/Action/ActionInterface.php"
    click CompositeAction "https://github.com/litesaml/lightsaml/blob/master/src/Action/CompositeAction.php"
    click ActionLogWrapper "https://github.com/litesaml/lightsaml/blob/master/src/Action/ActionLogWrapper.php"
    click DispatchEventAction "https://github.com/litesaml/lightsaml/blob/master/src/Action/DispatchEventAction.php"
    click AbstractProfileBuilder "https://github.com/litesaml/lightsaml/blob/master/src/Builder/Profile/AbstractProfileBuilder.php"
    click ProfileContext "https://github.com/litesaml/lightsaml/blob/master/src/Context/Profile/ProfileContext.php"
    click AssertionContext "https://github.com/litesaml/lightsaml/blob/master/src/Context/Profile/AssertionContext.php"
    click EndpointContext "https://github.com/litesaml/lightsaml/blob/master/src/Context/Profile/EndpointContext.php"
    click X509CredentialFileProvider "https://github.com/litesaml/lightsaml/blob/master/src/Provider/Credential/X509CredentialFileProvider.php"
    click CredentialResolverInterface "https://github.com/litesaml/lightsaml/blob/master/src/Resolver/Credential/CredentialResolverInterface.php"
    click CompositeCredentialStore "https://github.com/litesaml/lightsaml/blob/master/src/Store/Credential/CompositeCredentialStore.php"
    click BuildContainer "https://github.com/litesaml/lightsaml/blob/master/src/Bridge/Pimple/Container/BuildContainer.php"
    click LightSamlException "https://github.com/litesaml/lightsaml/blob/master/src/Error/LightSamlException.php"
    click MessageReceived "https://github.com/litesaml/lightsaml/blob/master/src/Event/MessageReceived.php"
    click MessageSent "https://github.com/litesaml/lightsaml/blob/master/src/Event/MessageSent.php"

    %% Styles
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef binding fill:#b9f6ca,stroke:#2e7d32,stroke-width:1px
    classDef datamodel fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef action fill:#ffcc80,stroke:#ef6c00,stroke-width:1px
    classDef profile fill:#e1bee7,stroke:#8e24aa,stroke-width:1px
    classDef provider fill:#80deea,stroke:#0097a7,stroke-width:1px
    classDef di fill:#cfd8dc,stroke:#607d8b,stroke-width:1px
    classDef error fill:#ff8a80,stroke:#d32f2f,stroke-width:1px
```
