# doorkeeper-gem/doorkeeper architecture

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

- Interactive diagram: https://gitdiagram.com/doorkeeper-gem/doorkeeper
- Repository: https://github.com/doorkeeper-gem/doorkeeper

## Overview

##### Main Components
- Views and Presentation: The app/views/doorkeeper directory contains view templates that support the user interface aspects (e.g., forms for authorizing client applications).
- Core OAuth Logic: The lib/doorkeeper directory is packed with modules and classes that contain the domain logic, such as OAuth flows, token generation, client credentials, and error handling. Subdirectories like lib/doorkeeper/oauth, lib/doorkeeper/orm, and lib/doorkeeper/grant_flow help modularize the core functionality.
- Active Record Integration: The ORM integration is visible in lib/doorkeeper/orm/active_record, which handles persistence and interaction with the database.
- Configuration and Setup: The gemspec and various generators in lib/generators/doorkeeper show how the engine can be installed and configured in a host application.

##### Relationships and Interactions
- Clients (external applications) interact with the OAuth endpoints (controllers) via HTTP.
- The controllers call into the business logic (in the lib/doorkeeper modules) to handle various flows like the Authorization Code Flow, Client Credentials, Resource Owner Password, etc.
- The ORM layer is used to persist data such as access tokens, authorization codes, and application data.
- There is a clear interaction between configuration (lib/doorkeeper/config) and how the OAuth flows are executed.
- Additional support files (e.g., in bin, config, and spec directories) indicate testing infrastructure and server bootstrapping for development or testing purposes.

##### Architectural Patterns & Design Principles
- Modular Design: Core OAuth functionalities are broken down into loosely coupled modules (see the directories for oauth, grant_flow, and generators).
- Rails Engine Integration: The project works as a Rails engine (packaged in lib/doorkeeper/engine.rb) so that it hooks into an existing Rails or Grape app.
- Extensibility: The design encourages extensions—for example, separate gems exist for OpenID Connect, JWT support, and additional grant flows, indicating an architecture that supports plug-in extensions.
- Separation of Concerns: There is a distinct separation between controllers, views, models, and the underlying business logic.

##### Relevant Technologies, Frameworks, and Libraries
- Ruby on Rails & Grape: The engine is built for Rails and optionally integrates with Grape.
- Active Record: Default ORM for persistence.
- Testing frameworks (RSpec and related specs under spec/) for ensuring correctness.

##### Elements
- “Core OAuth Logic” (lib/doorkeeper modules such as oauth flows and grant flows)
- “ORM / Persistence Layer” (ActiveRecord models under lib/doorkeeper/orm)
- “UI / Views” (templates under app/views/doorkeeper)
- “Configuration & Initialization” (engine and generators)

## Diagram (Mermaid)

```mermaid
flowchart TD
    ExternalClient("External OAuth Client"):::external

    subgraph "Web/API Layer"
        AController("ApplicationsController"):::endpoint
        AuthController("AuthorizationsController"):::endpoint
        TController("TokensController"):::endpoint
    end

    subgraph "UI / Views"
        Views("View Templates"):::view
    end

    subgraph "Core OAuth Business Logic"
        Core("Core OAuth Logic"):::logic
        OAuthFlows("OAuth Flows"):::logic
        GrantFlows("Grant Flow Modules"):::logic
        ErrorHandling("Error Handling"):::logic
    end

    subgraph "Data Persistence Layer"
        ORM("Active Record ORM"):::persistence
    end

    subgraph "Configuration & Initialization"
        Engine("Rails Engine"):::config
        Generators("Generators"):::config
        GemSpec("Gem Specification"):::config
    end

    %% Connections from External Client to Controllers
    ExternalClient -->|"HTTP_Request"| AController
    ExternalClient -->|"HTTP_Request"| AuthController
    ExternalClient -->|"HTTP_Request"| TController

    %% Connections from Controllers to Core OAuth Logic
    AController -->|"calls"| Core
    AuthController -->|"calls"| Core
    TController -->|"calls"| Core

    %% Controllers rendering UI
    AController -->|"renders"| Views
    AuthController -->|"renders"| Views
    TController -->|"renders"| Views

    %% Core OAuth Logic breakdown and persistence
    Core -->|"handles"| OAuthFlows
    Core -->|"handles"| GrantFlows
    Core -->|"handles"| ErrorHandling
    Core -->|"persists"| ORM

    %% Configuration links to Core Logic
    Engine -->|"configures"| Core
    Generators -->|"sets_up"| Core
    GemSpec -->|"defines"| Core

    %% Styles
    classDef external fill:#f88,stroke:#333,stroke-width:2px;
    classDef endpoint fill:#bbf,stroke:#333,stroke-width:2px;
    classDef view fill:#aaf,stroke:#333,stroke-width:2px;
    classDef logic fill:#afa,stroke:#333,stroke-width:2px;
    classDef persistence fill:#ff8,stroke:#333,stroke-width:2px;
    classDef config fill:#ddd,stroke:#333,stroke-width:2px;

    %% Click Events
    click AController "https://github.com/doorkeeper-gem/doorkeeper/tree/main/app/controllers/doorkeeper"
    click AuthController "https://github.com/doorkeeper-gem/doorkeeper/tree/main/app/controllers/doorkeeper"
    click TController "https://github.com/doorkeeper-gem/doorkeeper/tree/main/app/controllers/doorkeeper"
    click Views "https://github.com/doorkeeper-gem/doorkeeper/tree/main/app/views/doorkeeper"
    click Core "https://github.com/doorkeeper-gem/doorkeeper/tree/main/lib/doorkeeper"
    click ORM "https://github.com/doorkeeper-gem/doorkeeper/tree/main/lib/doorkeeper/orm/active_record"
    click Engine "https://github.com/doorkeeper-gem/doorkeeper/blob/main/lib/doorkeeper/engine.rb"
    click Generators "https://github.com/doorkeeper-gem/doorkeeper/tree/main/lib/generators/doorkeeper"
    click GemSpec "https://github.com/doorkeeper-gem/doorkeeper/blob/main/doorkeeper.gemspec"
```
