# bellps/slonito architecture

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

- Interactive diagram: https://gitdiagram.com/bellps/slonito
- Repository: https://github.com/bellps/slonito

## Overview

##### Project Type and Purpose
- This is a full-stack Ruby on Rails 7 application (“Slonito”) that provides a real-time chat interface backed by an external AI service.
- Key features:
- User authentication and management via Devise
- Chat & message persistence (models: Chat, ChatMessage)
- Real-time updates using ActionCable (WebSockets)
- Stimulus/Turbo front-end for dynamic interactions
- Service objects for AI integration (SlonitoApiService) and SQL validation

##### Top-Level Architecture Overview
[Browser (Client)]
↕ HTTP/Turbo Frames
[Rails Web Server (Puma + Controllers + Views + Stimulus)]
↕ WebSocket (ActionCable)
[Background Workers (ActiveJob) & Services]
↕
[Persistent Storage & External Services]

##### Main Components
a. Client Layer
- Browser UI with Rails-generated HTML, Turbo Frames, Stimulus controllers (chat_controller.js, message_input_controller.js, etc.), Tailwind CSS.
- Components folder: custom view components for chat UI (chat_button_component, message_component, etc.).

b. Web Server Layer
- Rails MVC:
- Controllers (ChatsController, ChatsMessagesController, MainController)
- Views (.html.erb, .html+turbo_frame.erb)
- Models (User, Chat, ChatMessage)
- Middleware & Rack: config.ru, Puma server.
- Authentication: Devise initializers, controllers, and mailers.

c. Real-Time Layer
- ActionCable channels (app/channels/application_cable/*)
- WebSocket connections for live chat updates.

d. Service & Worker Layer
- Service Objects:
- SlonitoApiService → wraps calls to the external AI provider.
- SqlValidationService → validates user-supplied SQL.
- ActiveJob (app/jobs) for asynchronous tasks (e.g., mailers, long-running API calls).

e. Data Layer
- PostgreSQL (via config/database.yml) for users, chats, messages.
- ActiveStorage (config/storage.yml) for attachments (if used).
- Redis (commonly used for ActionCable pub/sub—mention if configured).

f. External Services
- AI provider (OpenAI or similar) called by SlonitoApiService.
- SMTP/Mail service for Devise mailers.
- Potential caching layer (Redis) if present in production.

##### Component Interactions & Data Flow
1. User logs in (Devise) → HTTP POST → SessionsController → Database → Devise mailer (if required).
2. User opens chat UI → HTTP GET → Rails renders view with Turbo Frames + Stimulus controllers.
3. User sends a message →
- Frontend Stimulus controller triggers POST to ChatsMessagesController
- Controller persists ChatMessage
- Broadcast via ActionCable to subscribed clients
- Background job invokes SlonitoApiService → external AI call → returns response → persisted as ChatMessage → broadcast back to client
4. SQL code submission (if feature used) → SqlValidationService validates → result returned in real-time.

##### Architectural Patterns & Design Principles
- MVC (Model-View-Controller) at core.
- Component-based views (Rails ViewComponent pattern).
- Service Objects for external integrations & business logic.
- Hotwire (Turbo + Stimulus) for minimal-JS interactivity.
- Asynchronous processing via ActiveJob.
- Real-time via ActionCable (pub/sub).

##### Capturing Essential Details
- Don’t omit: authentication flow (Devise), real-time channel, AI service integration, database writes/reads, and background processing.
- Configurable components: Docker container, environment variables (.env.example), credentials (config/credentials.yml.enc).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Client
    subgraph "Client Layer" 
        direction TB
        Browser["Browser UI"]:::client
        Stimulus["Stimulus Controllers\n(chat, message_input, chat_list, form_submission, markdown, modal, schema_modal)"]:::client
    end

    %% Layer 2: Web Server
    subgraph "Rails App (Web Server)" 
        direction TB
        MVC["Rails MVC\nControllers, Views, Models"]:::web
        DeviseAuth["Devise Authentication"]:::web
        ActionCable["ActionCable\nChannels & Connections"]:::web
        PumaRack["Puma + Rack (config.ru, puma.rb)"]:::web
        Turbo["Turbo Frames & Hotwire"]:::web
        ViewComponents["ViewComponents\n(Chat UI Components)"]:::web
    end

    %% Layer 3: Services & Workers
    subgraph "Services & Workers" 
        direction TB
        SlonitoService["SlonitoApiService"]:::service
        SQLService["SqlValidationService"]:::service
        ActiveJob["ActiveJob Jobs"]:::service
    end

    %% Layer 4: Data & External
    subgraph "Data & External" 
        direction TB
        Postgres["PostgreSQL"]:::data
        Redis["Redis"]:::data
        AIProvider["External AI Provider"]:::data
        SMTP["SMTP/Mail Service"]:::data
        Storage["ActiveStorage"]:::data
    end

    %% Connections
    Browser -->|"HTTP/Turbo Frames"| MVC
    Browser -->|"WebSocket"| ActionCable
    Stimulus --> MVC
    MVC -->|"enqueue job"| ActiveJob
    MVC -->|"call service"| SlonitoService
    MVC -->|"call service"| SQLService
    ActionCable -->|"broadcast"| Browser
    ActiveJob -.->|"async HTTP"| AIProvider
    ActiveJob -.->|"async mail"| SMTP
    MVC -->|"read/write"| Postgres
    MVC -->|"read/write"| Storage
    ActionCable --> Redis
    ActiveJob --> Redis

    %% Click Events
    click Browser "https://github.com/bellps/slonito/blob/main/app/javascript/application.js"
    click Stimulus "https://github.com/bellps/slonito/blob/main/app/javascript/controllers/chat_controller.js"
    click Stimulus "https://github.com/bellps/slonito/blob/main/app/javascript/controllers/message_input_controller.js"
    click Stimulus "https://github.com/bellps/slonito/blob/main/app/javascript/controllers/chat_list_controller.js"
    click Stimulus "https://github.com/bellps/slonito/blob/main/app/javascript/controllers/form_submission_controller.js"
    click Stimulus "https://github.com/bellps/slonito/blob/main/app/javascript/controllers/markdown_controller.js"
    click Stimulus "https://github.com/bellps/slonito/blob/main/app/javascript/controllers/modal_controller.js"
    click Stimulus "https://github.com/bellps/slonito/blob/main/app/javascript/controllers/schema_modal_controller.js"
    click MVC "https://github.com/bellps/slonito/blob/main/app/controllers/chats_controller.rb"
    click MVC "https://github.com/bellps/slonito/blob/main/app/controllers/chats_messages_controller.rb"
    click MVC "https://github.com/bellps/slonito/blob/main/app/controllers/main_controller.rb"
    click MVC "https://github.com/bellps/slonito/blob/main/app/models/chat.rb"
    click MVC "https://github.com/bellps/slonito/blob/main/app/models/chat_message.rb"
    click DeviseAuth "https://github.com/bellps/slonito/blob/main/config/initializers/devise.rb"
    click DeviseAuth "https://github.com/bellps/slonito/blob/main/app/models/user.rb"
    click DeviseAuth "https://github.com/bellps/slonito/tree/main/app/views/devise/"
    click ViewComponents "https://github.com/bellps/slonito/blob/main/app/components/chat_component.rb"
    click ViewComponents "https://github.com/bellps/slonito/blob/main/app/components/chat_button_component.rb"
    click ViewComponents "https://github.com/bellps/slonito/blob/main/app/components/message_component.rb"
    click ViewComponents "https://github.com/bellps/slonito/blob/main/app/components/message_input_component.rb"
    click ActionCable "https://github.com/bellps/slonito/blob/main/app/channels/application_cable/channel.rb"
    click ActionCable "https://github.com/bellps/slonito/blob/main/app/channels/application_cable/connection.rb"
    click SlonitoService "https://github.com/bellps/slonito/blob/main/app/services/slonito_api_service.rb"
    click SQLService "https://github.com/bellps/slonito/blob/main/app/services/sql_validation_service.rb"
    click ActiveJob "https://github.com/bellps/slonito/blob/main/app/jobs/application_job.rb"
    click Postgres "https://github.com/bellps/slonito/blob/main/config/database.yml"
    click Storage "https://github.com/bellps/slonito/blob/main/config/storage.yml"
    click PumaRack "https://github.com/bellps/slonito/blob/main/config.ru"
    click PumaRack "https://github.com/bellps/slonito/blob/main/config/puma.rb"
    click SMTP "https://github.com/bellps/slonito/blob/main/app/mailers/application_mailer.rb"
    click SMTP "https://github.com/bellps/slonito/tree/main/app/views/devise/mailer/"
    click Redis "https://github.com/bellps/slonito/blob/main/config/cable.yml"
    click Redis "https://github.com/bellps/slonito/blob/main/config/cable.yml"
    classDef client fill:#D0E8FF,stroke:#004E8C,color:#004E8C;
    classDef web fill:#DFF2D8,stroke:#3C763D,color:#3C763D;
    classDef service fill:#FFE3B8,stroke:#B36B00,color:#B36B00;
    classDef data fill:#EEEEEE,stroke:#666666,color:#333333;
```
