# wemrekurt/rails-api-boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/wemrekurt/rails-api-boilerplate
- Repository: https://github.com/wemrekurt/rails-api-boilerplate

## Overview

##### Project type and purpose
- This is a Rails-based API boilerplate (no built-in frontend) designed to expose RESTful endpoints for user authentication, registration, password management, token issuance (via Doorkeeper), background jobs (via Sidekiq), and real-time channels (via ActionCable).
- It uses a clean “controller → operation → contract → service → model” layering, with Swagger for API documentation and Ransack/Kaminari for searching and pagination.

##### File structure
- Top-level key folders:
- app/controllers (request & routing)
- app/operations + app/contracts (business orchestration & input validation)
- app/services (core business rules & integrations)
- app/models (ActiveRecord/DB mapping)
- app/jobs (Sidekiq background processing)
- app/channels (ActionCable real-time)
- config/routes, initializers (Devise, Doorkeeper, CORS, Sidekiq)
- db (PostgreSQL migrations & schema)
- Swagger docs under app/swagger_docs and docs/SWAGGER.md
- External dependencies/config:
- Redis (for Sidekiq and ActionCable pub/sub)
- PostgreSQL (primary data store)
- Puma (web server)
- Doorkeeper + Devise (OAuth2 & user auth)
- Ransack + Kaminari (search/sort/pagination)

##### README for insights
Request → ApplicationController → ApplicationOperation → ApplicationContract → ApplicationService → Response
- Sections reference Swagger, Service/Contract generators, and Ransack filters.

- Rectangles for synchronous layers (Controller, Operation, Service, Model)
- Rounded rectangles for background workers (Sidekiq) and real-time channels (ActionCable)
- Presentation (blue), Orchestration/Validation (yellow), Business Logic (green), Persistence (orange), Async/Real-time (purple)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "Clients" 
        direction TB
        APIConsumer["API Consumer<br/>(Web/Mobile)"]:::external
        OAuthClients["External OAuth Clients"]:::external
    end

    %% Load Balancing & Server
    subgraph "Server Layer"
        direction TB
        LoadBalancer["Load Balancer<br/>(AWS ELB)"]:::infrastructure
        Puma["Puma Web Server"]:::infrastructure
    end

    %% Rails Application Layers
    subgraph "Rails Application" 
        direction TB

        subgraph "Presentation Layer" 
            direction TB
            Router["Router<br/>(config/routes)"]:::presentation
            Controllers["Controllers"]:::presentation
        end

        subgraph "Orchestration Layer"
            direction TB
            Operations["Operations"]:::orchestration
            Contracts["Contracts"]:::orchestration
        end

        subgraph "Business Logic Layer"
            direction TB
            Services["Services"]:::business
        end

        subgraph "Persistence Layer"
            direction TB
            Models["Models"]:::persistence
            Postgres["PostgreSQL"]:::database
        end

    end

    %% Async & Real-Time
    subgraph "Async & Real-Time"
        direction TB
        Redis["Redis"]:::database
        Sidekiq["Sidekiq Workers"]:::async
        ActionCable["ActionCable Server"]:::async
    end

    %% Swagger Documentation
    SwaggerUI["Swagger UI / Docs"]:::documentation

    %% Connections
    APIConsumer -->|“HTTPS Request”| LoadBalancer
    OAuthClients -->|“OAuth2 Flow”| Router

    LoadBalancer --> Puma
    Puma --> Router
    Router --> Controllers
    Controllers --> Operations
    Operations --> Contracts
    Contracts --> Services
    Services --> Models
    Models --> Postgres

    Services -->|“enqueue job”| Redis
    Redis --> Sidekiq
    Sidekiq --> Services

    APIConsumer -->|“WebSocket Subscribe”| ActionCable
    ActionCable --> Redis
    Services -->|“broadcast”| ActionCable
    ActionCable --> APIConsumer

    APIConsumer -->|“/swagger”| SwaggerUI
    SwaggerUI --> Controllers

    %% Click Events
    click Puma "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/config/puma.rb"
    click Router "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/config/routes.rb"
    click Controllers "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/controllers/application_controller.rb"
    click Operations "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/operations/application_operation.rb"
    click Contracts "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/contracts/application_contract.rb"
    click Services "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/services/application_service.rb"
    click Models "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/models/application_record.rb"
    click Postgres "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/db/schema.rb"
    click Sidekiq "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/jobs/application_job.rb"
    click ActionCable "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/channels/application_cable/connection.rb"
    click SwaggerUI "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/swagger_docs/swagger_docs.rb"
    click Controllers "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/config/routes/authentication.rb"
    click Controllers "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/controllers/users/registrations_controller.rb"
    click Controllers "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/controllers/users/passwords_controller.rb"
    click Controllers "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/controllers/users/tokens_controller.rb"
    click Controllers "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/controllers/swagger_controller.rb"
    click Operations "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/operations/users/registrations/create_operation.rb"
    click Operations "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/operations/users/passwords/create_operation.rb"
    click Operations "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/operations/users/passwords/update_operation.rb"
    click Contracts "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/contracts/users/registrations/register_contract.rb"
    click Contracts "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/contracts/users/passwords/send_instructions_contract.rb"
    click Contracts "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/contracts/users/passwords/update_contract.rb"
    click Services "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/services/doorkeeper_service/access_tokens/create.rb"
    click Services "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/services/users_service/registrations/register.rb"
    click Services "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/services/users_service/passwords/send_instructions.rb"
    click Services "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/services/users_service/passwords/update.rb"
    click Services "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/services/users_service/create.rb"
    click Models "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/models/user.rb"
    click Postgres "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/db/migrate/20220212185845_devise_create_users.rb"
    click Postgres "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/db/migrate/20220212195921_create_doorkeeper_tables.rb"
    click Postgres "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/db/schema.rb"
    click Sidekiq "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/config/sidekiq.yml"
    click Sidekiq "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/lib/supports/sidekiq/helper.rb"
    click ActionCable "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/config/cable.yml"
    click SwaggerUI "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/docs/SWAGGER.md"
    click SwaggerUI "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/views/layouts/swagger.html.erb"
    click Controllers "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/controllers/concerns/doorkeeper/authorize.rb"
    click SwaggerUI "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/swagger_docs/controllers/users/passwords_controller.rb"
    click SwaggerUI "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/swagger_docs/controllers/users/registrations_controller.rb"
    click SwaggerUI "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/app/swagger_docs/controllers/users/tokens_controller.rb"
    click Controllers "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/config/initializers/devise.rb"
    click Controllers "https://github.com/wemrekurt/rails-api-boilerplate/blob/main/config/initializers/doorkeeper.rb"

    %% Styles
    classDef external fill:#D6EAF8,stroke:#2980B9
    classDef infrastructure fill:#EBF5FB,stroke:#5DADE2
    classDef presentation fill:#D5F5E3,stroke:#27AE60
    classDef orchestration fill:#FCF3CF,stroke:#F1C40F
    classDef business fill:#D5F5F6,stroke:#8E44AD
    classDef persistence fill:#FDEBD0,stroke:#D35400
    classDef database fill:#FADBD8,stroke:#C0392B,stroke-dasharray: 5 5
    classDef async fill:#E8DAEF,stroke:#9B59B6,stroke-dasharray: 2 2
    classDef documentation fill:#FEF9E7,stroke:#F39C12,stroke-dasharray: 1 2 1 2
```
