# tomlobato/riff architecture

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

- Interactive diagram: https://gitdiagram.com/tomlobato/riff
- Repository: https://github.com/tomlobato/riff

## Overview

- API Gateway / Request Routing: Represent the Roda application (sample_app/app.rb and its route definitions). This component directs incoming HTTP requests to the corresponding routes (e.g., session handling and actions).
- Riff Core Engine: This is encapsulated in the lib/riff directory and includes:
- Action Handlers: Modules under lib/riff/actions (with sub-files for create, delete, update, show, etc.) which manage the core CRUD and custom actions.
- Authentication & Authorization: Components under lib/riff/auth and lib/riff/authorize that contain different auth methods (default, request, signin) and token management (e.g., token creation, validation, and update).
- Request Processing Pipeline: Under lib/riff/request there are modules and classes that build the request chain, context, validation, response composition, and error handling (including chain, context, and validate components).
- Session Management: Represented under lib/riff/session handling open, close, and refresh operations.
- Utility, Configuration, and Constants: Modules such as lib/riff/conf, lib/riff/constants, and lib/riff/settings offer configuration management and shared utility methods.
- Additional Components:
- Swagger Documentation: Under lib/riff/swagger, which shows that the gem supports (or aims to support) API documentation.
- External Dependencies: Libraries such as Roda, Sequel, ActiveSupport, and dry-validation play a significant role in the functionality.
- Sample App Components: In sample_app/, include:
- API resources and routes – Organized in app/api, which include resources for company, post, user, etc.
- Models – Represented in sample_app/app/models.
- Bootstrapping and Environment – Present in sample_app/system (boot files for database, logging, redis, etc.) and configuration files.
- Testing – Presence of a well-defined test suite in spec/ and sample_app/spec to ensure full coverage.

##### Relationships and Interactions
- Data Flow: Start with HTTP requests entering via the Roda routing layer (r.post, r.on in app.rb), then transferring control to the Riff methods (handle_session, handle_action).
- Request Handling Pipeline: The request is passed on to the modules that:
- Validate and process parameters.
- Handle authorization and authentication (verifying tokens or credentials).
- Direct valid requests to appropriate action handlers (CRUD operations).
- Handle responses by building response bodies and managing errors.
- External Tools: Include external libraries (Roda, Sequel, dry-validation, Oj) as part of the environment that supports and integrates with the core functionalities.

##### Architectural Patterns/Design Principles
- Layered Architecture: Demonstrate separation of concerns (routing, processing, validation, authentication, and data access).
- Modular Design: Show how functionalities are grouped in logical directories (e.g., actions, auth, request, session) making the gem extensible and maintainable.
- Extensibility Points: Mark the areas where developers can override default behaviors (custom actions under Actions::<MODEL> and custom validations).

##### Detailed Steps for the Principal Software Engineer
- Create individual blocks for the following:
- API Gateway (Roda routes) that distributes requests.
- Riff Core Engine with sub-blocks: Action Handlers, Authentication & Authorization, Request Processing Pipeline, Session Handling, and Configuration.
- Sample App Implementation which demonstrates how Riff is integrated.
- Under “External Dependencies and Libraries”, list Roda, Sequel, ActiveSupport, dry-validation, Oj.
- Inbound request flow: User → API Gateway → Riff Core Engine → Database/Models → Response.
- Where customization occurs (e.g., custom actions under Actions::<MODEL>).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    User["Client (User)"]:::external

    %% API Gateway
    subgraph "API Gateway"
        APIRouting["Roda Routing"]:::api
    end

    %% Riff Core Engine
    subgraph "Riff Core Engine"
        RequestPipeline["Request Processing Pipeline"]:::core
        Authentication["Authentication"]:::core
        Authorization["Authorization"]:::core
        ActionHandlers["Action Handlers"]:::core
        SessionManagement["Session Management"]:::core
        SwaggerDoc["Swagger Documentation"]:::core
        %% Configuration & Utilities as subgraph
        subgraph "Configuration & Utilities"
            Config["Configuration (conf.rb)"]:::core
            Constants["Constants (constants.rb)"]:::core
            Settings["Settings (settings.rb)"]:::core
            Utility["Utility (util.rb)"]:::core
        end
    end

    %% Sample App Implementation
    subgraph "Sample App Implementation"
        APIResources["API Resources & Routes"]:::sample
        Models["Models"]:::sample
        Bootstrapping["Bootstrapping & Environment"]:::sample
        Testing["Testing"]:::sample
    end

    %% External Dependencies
    subgraph "External Dependencies"
        RodaLib["Roda"]:::external
        SequelLib["Sequel"]:::external
        ActiveSupportLib["ActiveSupport"]:::external
        DryValidationLib["dry-validation"]:::external
        OjLib["Oj"]:::external
    end

    %% Connections
    User -->|"HTTPRequest"| APIRouting
    APIRouting -->|"routes"| RequestPipeline
    APIRouting -->|"apiCalls"| APIResources
    APIRouting -->|"docs"| SwaggerDoc

    RequestPipeline -->|"authenticate"| Authentication
    Authentication -->|"authorize"| Authorization
    Authorization -->|"execute"| ActionHandlers
    RequestPipeline -->|"handleSession"| SessionManagement
    RequestPipeline -->|"validate"| Config
    Bootstrapping -->|"configures"| Config
    ActionHandlers -->|"CRUD"| Models

    %% Internal links within Configuration & Utilities
    Config ---|"shares"| Constants
    Config ---|"shares"| Settings
    Config ---|"shares"| Utility

    %% External dependencies connections
    RodaLib --> APIRouting
    SequelLib --> Models
    DryValidationLib --> RequestPipeline
    OjLib --> RequestPipeline
    ActiveSupportLib --> Config

    %% Click Events for API Gateway & Riff Core Engine
    click APIRouting "https://github.com/tomlobato/riff/blob/main/sample_app/app.rb"
    click ActionHandlers "https://github.com/tomlobato/riff/tree/main/lib/riff/actions"
    click Authentication "https://github.com/tomlobato/riff/tree/main/lib/riff/auth"
    click Authorization "https://github.com/tomlobato/riff/blob/main/lib/riff/authorize.rb"
    click RequestPipeline "https://github.com/tomlobato/riff/tree/main/lib/riff/request"
    click SessionManagement "https://github.com/tomlobato/riff/tree/main/lib/riff/session"
    click Config "https://github.com/tomlobato/riff/blob/main/lib/riff/conf.rb"
    click Constants "https://github.com/tomlobato/riff/blob/main/lib/riff/constants.rb"
    click Settings "https://github.com/tomlobato/riff/blob/main/lib/riff/settings.rb"
    click Utility "https://github.com/tomlobato/riff/blob/main/lib/riff/util.rb"
    click SwaggerDoc "https://github.com/tomlobato/riff/tree/main/lib/riff/swagger"

    %% Click Events for Sample App Components
    click APIResources "https://github.com/tomlobato/riff/tree/main/sample_app/app/api"
    click Models "https://github.com/tomlobato/riff/tree/main/sample_app/app/models"
    click Bootstrapping "https://github.com/tomlobato/riff/tree/main/sample_app/system"
    click Testing "https://github.com/tomlobato/riff/tree/main/sample_app/spec"

    %% Styles
    classDef api fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef core fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef sample fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
