# jaykava/sso-server architecture

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

- Interactive diagram: https://gitdiagram.com/jaykava/sso-server
- Repository: https://github.com/jaykava/sso-server

## Overview

##### Project type and purpose
- This is a Ruby on Rails full-stack web application that acts as an OAuth 2.0 provider and user management system.
- It uses Devise for user authentication, custom controllers for OAuth client registration and token flows, Stimulus (via importmap) for minimal JavaScript interactivity, Action Cable for real-time channels, and Active Job/Mailers for background tasks and email notifications.

##### File structure
- Top-level Ruby/Rails standard layout:
- app/controllers, app/models, app/views → MVC pattern
- app/assets & app/javascript → asset pipeline + Stimulus controllers
- app/channels → real-time features via Action Cable
- app/mailers, app/jobs → background processing and email
- config/ holds environment configs, routes, cable (WebSocket), and Puma (app server).
- db/ has migrations for users, OAuth clients, access grants.
- Bin, Rakefile, Dockerfile → build/deploy scripts.
- Test/ covers unit, integration, system tests.
- Uses importmap (no Webpack) and Jbuilder for JSON endpoints.

##### README
- Placeholder README; no architecture details. We infer architecture entirely from file tree.

##### Detail checklist
- Controller cluster (AuthController, OAuthClientsController, DashboardController).
- Devise workflow: Sign-up, Sign-in, Password reset via mailers.
- Jbuilder rendering JSON for API consumers.
- Environment/deployment aspects if relevant (Docker → Puma).
- Don’t overcrowd: group related internals (e.g., all app/models) but call out domain models.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser (User UI)"]:::external
    OAuthClientExt["External OAuth Client"]:::external
    SMTP["SMTP Service"]:::external
    PostgreSQL["PostgreSQL DB"]:::infra
    JobQueue["Job Queue"]:::infra
    StorageSvc["Storage Service (Active Storage)"]:::infra

    subgraph "Rails Application" 
        direction TB
        subgraph "MVC Core"
            direction TB
            ApplicationController["ApplicationController"]:::rails
            ApplicationRecord["ApplicationRecord"]:::rails
            LayoutView["Layout View"]:::rails
        end
        subgraph "User Authentication (Devise)"
            direction TB
            DeviseInit["Devise Initializer"]:::rails
            UserModel["User Model"]:::rails
            DeviseViews["Devise Views"]:::rails
            DeviseMailerTemplates["Devise Mailer Templates"]:::rails
        end
        subgraph "OAuth 2.0 Provider API"
            direction TB
            OAuthClientsController["OAuthClientsController"]:::rails
            AuthController["AuthController"]:::rails
            OAuthClientModel["OAuthClient Model"]:::rails
            AccessGrantModel["AccessGrant Model"]:::rails
            OAuthJbuilder["OAuthClients Jbuilder Views"]:::rails
            Routes["Routes (OAuth Endpoints)"]:::rails
            OAuthMigrate1["Create OAuthClients Migration"]:::rails
            OAuthMigrate2["Create AccessGrants Migration"]:::rails
        end
        subgraph "Dashboard UI"
            direction TB
            DashboardController["DashboardController"]:::rails
            DashboardView["Dashboard View"]:::rails
        end
        subgraph "Stimulus Frontend"
            direction TB
            Importmap["Importmap Config"]:::rails
            JSApp["application.js"]:::rails
            StimulusControllers["Stimulus Controllers"]:::rails
        end
        subgraph "Real-time Channels"
            direction TB
            CableConnection["Cable Connection"]:::rails
            CableChannel["Cable Channel"]:::rails
            CableConfig["cable.yml"]:::rails
        end
        subgraph "Asynchronous Services"
            direction TB
            ApplicationJob["ApplicationJob"]:::rails
            ApplicationMailer["ApplicationMailer"]:::rails
        end
        subgraph "Database & Storage"
            direction TB
            Schema["schema.rb"]:::rails
            Seeds["seeds.rb"]:::rails
            StorageConfig["storage.yml"]:::rails
            Blobs["Local Blobs"]:::rails
        end
        subgraph "Deployment & Infrastructure"
            direction TB
            DockerfileNode["Dockerfile"]:::rails
            Entrypoint["bin/docker-entrypoint"]:::rails
            PumaConfig["puma.rb"]:::rails
            RackEntry["config.ru"]:::rails
        end
    end

    %% Connections
    Browser -->|"HTTP Requests"| ApplicationController
    Browser -->|"WebSocket"| CableConnection
    OAuthClientExt -->|"API Calls"| AuthController
    ApplicationController -->|renders| LayoutView
    ApplicationController -->|invokes| UserModel
    UserModel -->|CRUD| PostgreSQL
    OAuthClientsController -->|manages| OAuthClientModel
    AuthController -->|handles| AccessGrantModel
    OAuthClientModel -->|CRUD| PostgreSQL
    AccessGrantModel -->|CRUD| PostgreSQL
    Routes -->|routes to| OAuthClientsController
    Routes -->|routes to| AuthController
    ApplicationController -->|enqueues| ApplicationJob
    ApplicationJob -->|queues in| JobQueue
    JobQueue -->|delivers via| SMTP
    ApplicationMailer -->|sends via| SMTP
    CableConnection -->|subscribes| CableChannel
    CableChannel -->|broadcasts| Browser
    JSApp -->|imports| StimulusControllers
    Importmap -->|configures| JSApp
    StorageSvc -->|stores| Blobs
    ApplicationController -->|uploads/downloads| StorageSvc
    RailsApp -->|connects to| PostgreSQL

    %% Click Events
    click ApplicationController "https://github.com/jaykava/sso-server/blob/master/app/controllers/application_controller.rb"
    click ApplicationRecord "https://github.com/jaykava/sso-server/blob/master/app/models/application_record.rb"
    click LayoutView "https://github.com/jaykava/sso-server/blob/master/app/views/layouts/application.html.erb"
    click DeviseInit "https://github.com/jaykava/sso-server/blob/master/config/initializers/devise.rb"
    click UserModel "https://github.com/jaykava/sso-server/blob/master/app/models/user.rb"
    click DeviseViews "https://github.com/jaykava/sso-server/tree/master/app/views/devise/"
    click DeviseMailerTemplates "https://github.com/jaykava/sso-server/tree/master/app/views/devise/mailer/"
    click OAuthClientsController "https://github.com/jaykava/sso-server/blob/master/app/controllers/oauth_clients_controller.rb"
    click AuthController "https://github.com/jaykava/sso-server/blob/master/app/controllers/auth_controller.rb"
    click OAuthClientModel "https://github.com/jaykava/sso-server/blob/master/app/models/oauth_client.rb"
    click AccessGrantModel "https://github.com/jaykava/sso-server/blob/master/app/models/access_grant.rb"
    click OAuthJbuilder "https://github.com/jaykava/sso-server/tree/master/app/views/oauth_clients/"
    click Routes "https://github.com/jaykava/sso-server/blob/master/config/routes.rb"
    click OAuthMigrate1 "https://github.com/jaykava/sso-server/blob/master/db/migrate/20240610092221_create_oauth_clients.rb"
    click OAuthMigrate2 "https://github.com/jaykava/sso-server/blob/master/db/migrate/20240610092229_create_access_grants.rb"
    click DashboardController "https://github.com/jaykava/sso-server/blob/master/app/controllers/dashboard_controller.rb"
    click DashboardView "https://github.com/jaykava/sso-server/blob/master/app/views/dashboard/index.html.erb"
    click Importmap "https://github.com/jaykava/sso-server/blob/master/config/importmap.rb"
    click JSApp "https://github.com/jaykava/sso-server/blob/master/app/javascript/application.js"
    click StimulusControllers "https://github.com/jaykava/sso-server/tree/master/app/javascript/controllers/"
    click CableConnection "https://github.com/jaykava/sso-server/blob/master/app/channels/application_cable/connection.rb"
    click CableChannel "https://github.com/jaykava/sso-server/blob/master/app/channels/application_cable/channel.rb"
    click CableConfig "https://github.com/jaykava/sso-server/blob/master/config/cable.yml"
    click ApplicationJob "https://github.com/jaykava/sso-server/blob/master/app/jobs/application_job.rb"
    click ApplicationMailer "https://github.com/jaykava/sso-server/blob/master/app/mailers/application_mailer.rb"
    click Schema "https://github.com/jaykava/sso-server/blob/master/db/schema.rb"
    click Seeds "https://github.com/jaykava/sso-server/blob/master/db/seeds.rb"
    click StorageConfig "https://github.com/jaykava/sso-server/blob/master/config/storage.yml"
    click Blobs "https://github.com/jaykava/sso-server/tree/master/storage/"
    click DockerfileNode "https://github.com/jaykava/sso-server/tree/master/Dockerfile"
    click Entrypoint "https://github.com/jaykava/sso-server/tree/master/bin/docker-entrypoint"
    click PumaConfig "https://github.com/jaykava/sso-server/blob/master/config/puma.rb"
    click RackEntry "https://github.com/jaykava/sso-server/blob/master/config.ru"

    %% Styles
    classDef external fill:#d4f4dd,stroke:#333,stroke-width:1px
    classDef rails fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef infra fill:#ffe0b2,stroke:#333,stroke-width:1px
```
