# chesszebra/lichess-oauth-server architecture

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

- Interactive diagram: https://gitdiagram.com/chesszebra/lichess-oauth-server
- Repository: https://github.com/chesszebra/lichess-oauth-server

## Overview

##### Key Architectural Patterns to Highlight

a. Middleware Architecture
- Pipeline configuration (config/pipeline.php)
- Route configuration (config/routes.php)

b. Dependency Injection
- Container configuration (config/container.php)
- Factory pattern implementation

c. Repository Pattern
- Access Tokens
- Auth Codes
- Clients
- Refresh Tokens
- Scopes

a. Client Application → Nginx → OAuth Server
b. OAuth Server → Storage Layer (PDO/MongoDB)
c. OAuth Server → Template Engine (Twig)
d. Command Line → OAuth Server (for administration)

##### Component Details

a. OAuth Entities (Group these together):
- AccessToken
- AuthCode
- Client
- RefreshToken
- Scope
- User

b. Template Layer:
- Twig template structure
- Custom template override capability

##### Critical Flows

a. Authorization Flow:
1. Client Request
2. Authorization Page Render
3. User Consent
4. Token Generation
5. Response

b. Token Management Flow:
1. Token Creation
2. Token Storage
3. Token Validation
4. Token Cleanup

##### Additional Elements

- Configuration Management
- Cache Layer
- Logging System
- Development vs Production Environments

##### Use clear boundaries to separate
- Public-facing components
- Internal services
- Storage layer
- Security infrastructure

##### Extension points
- Custom template integration
- Storage layer flexibility
- Repository pattern implementation

This structure will provide a clear understanding of how the application handles OAuth requests, manages tokens, and interacts with its storage layer while maintaining security and configurability.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Web Layer"
        NGINX["Nginx Reverse Proxy"]:::web
        ENTRY["Public Entry Point"]:::web
    end

    subgraph "OAuth Core"
        AUTH["Authorization Endpoint"]:::oauth
        TOKEN["Token Endpoint"]:::oauth
        CLI["Command Line Interface"]:::cli
        BEARER["Bearer Token Response"]:::oauth
    end

    subgraph "Storage Layer"
        PDO["PDO Storage"]:::storage
        MONGO["MongoDB Storage"]:::storage
    end

    subgraph "Entity Layer"
        ACCESS["Access Token"]:::entity
        AUTHCODE["Auth Code"]:::entity
        CLIENT["Client"]:::entity
        REFRESH["Refresh Token"]:::entity
        SCOPE["Scope"]:::entity
        USER["User"]:::entity
    end

    subgraph "Configuration"
        PIPELINE["Pipeline Config"]:::config
        ROUTES["Route Config"]:::config
        CONTAINER["Container Config"]:::config
    end

    subgraph "Template Layer"
        LAYOUT["Main Layout"]:::template
        OAUTH_TPL["OAuth Authorization Template"]:::template
        ERROR_TPL["Error Templates"]:::template
    end

    subgraph "Token Management"
        CLEANUP["Token Cleanup"]:::management
        CREATE_CLIENT["Client Creation"]:::management
    end

    %% Relationships
    NGINX --> ENTRY
    ENTRY --> AUTH
    ENTRY --> TOKEN
    
    AUTH --> PDO
    AUTH --> MONGO
    TOKEN --> PDO
    TOKEN --> MONGO
    
    CLI --> CLEANUP
    CLI --> CREATE_CLIENT
    
    AUTH --> OAUTH_TPL
    TOKEN --> BEARER
    
    PDO --> ACCESS
    PDO --> AUTHCODE
    PDO --> CLIENT
    PDO --> REFRESH
    PDO --> SCOPE
    PDO --> USER
    
    MONGO --> ACCESS
    MONGO --> AUTHCODE
    MONGO --> CLIENT
    MONGO --> REFRESH
    MONGO --> SCOPE
    MONGO --> USER

    %% Styles
    classDef web fill:#3498db
    classDef oauth fill:#e67e22
    classDef storage fill:#2ecc71
    classDef entity fill:#9b59b6
    classDef config fill:#f1c40f
    classDef template fill:#1abc9c
    classDef management fill:#e74c3c
    classDef cli fill:#34495e

    %% Click Events
    click NGINX "https://github.com/chesszebra/lichess-oauth-server/tree/master/data/docker/nginx/etc/nginx"
    click AUTH "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/Action/OAuthAuthorize.php"
    click TOKEN "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/Action/OAuthToken.php"
    click CLI "https://github.com/chesszebra/lichess-oauth-server/blob/master/bin/console.php"
    click PDO "https://github.com/chesszebra/lichess-oauth-server/tree/master/src/App/OAuth/Repository/Pdo"
    click MONGO "https://github.com/chesszebra/lichess-oauth-server/tree/master/src/App/OAuth/Repository/Mongo"
    click ACCESS "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/OAuth/Entity/AccessToken.php"
    click AUTHCODE "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/OAuth/Entity/AuthCode.php"
    click CLIENT "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/OAuth/Entity/Client.php"
    click REFRESH "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/OAuth/Entity/RefreshToken.php"
    click SCOPE "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/OAuth/Entity/Scope.php"
    click USER "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/OAuth/Entity/User.php"
    click PIPELINE "https://github.com/chesszebra/lichess-oauth-server/blob/master/config/pipeline.php"
    click ROUTES "https://github.com/chesszebra/lichess-oauth-server/blob/master/config/routes.php"
    click CONTAINER "https://github.com/chesszebra/lichess-oauth-server/blob/master/config/container.php"
    click LAYOUT "https://github.com/chesszebra/lichess-oauth-server/blob/master/templates/layout/default.html.twig"
    click OAUTH_TPL "https://github.com/chesszebra/lichess-oauth-server/blob/master/templates/app/oauth-authorize.html.twig"
    click ERROR_TPL "https://github.com/chesszebra/lichess-oauth-server/tree/master/templates/error"
    click CLEANUP "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/Command/ClearTokens.php"
    click CREATE_CLIENT "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/Command/CreateClient.php"
    click BEARER "https://github.com/chesszebra/lichess-oauth-server/blob/master/src/App/OAuth/ResponseTypes/BearerTokenResponse.php"
    click ENTRY "https://github.com/chesszebra/lichess-oauth-server/blob/master/public/index.php"
```
