# cpeggy/cl3 architecture

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

- Interactive diagram: https://gitdiagram.com/cpeggy/cl3
- Repository: https://github.com/cpeggy/cl3

## Overview

##### Project type and purpose
- This is a Ruby on Rails 7 monolithic full-stack web application.
- The README is a standard Rails template, indicating this app handles HTTP requests, template rendering, asset management, background jobs, websockets (Action Cable), mailing, and file uploads.

##### File structure
- Top-level Ruby/Rails files: Gemfile, Rakefile, config.ru, bin/, config/, lib/, db/, public/, storage/, test/.
- app/ contains the MVC layers:
- app/controllers → Rails controllers handling HTTP requests.
- app/models → ActiveRecord models mapping to database tables.
- app/views → ERB templates for HTML emails and page rendering.
- app/assets & app/javascript → asset pipeline and import-map-driven frontend with Stimulus controllers.
- app/channels → Action Cable WebSocket channels.
- app/jobs → ActiveJob background tasks.
- app/mailers → ActionMailer classes for email delivery.
- config/ holds environment setups, database.yml, routes.rb, importmap.rb, cable.yml, storage.yml.
- db/ seeds and schema migrations (not shown but implied).
- storage/ for Active Storage local files.
- public/ for static error pages and robots.txt.
- test/ for system, integration, unit tests.

##### Key architectural patterns and stacks
- MVC pattern at its core.
- Single monolithic application server (Puma) serving web requests.
- Importmap + Stimulus for progressive enhancement on the frontend.
- ActiveRecord for relational DB (likely PostgreSQL).
- Active Job with an adapter (Sidekiq/Resque) for background processing.
- Action Cable for real-time WebSockets.
- Active Storage for file uploads and storage.
- Action Mailer for outbound emails.

a. Main components
- Client (Browser or HTTP client)
- Web Server (Puma)
- Rails Application
– Router & Middleware Stack
– Controllers
– Views/Asset Pipeline (Sprockets + Importmap + Stimulus)
– Models (ActiveRecord)
– Jobs (ActiveJob)
– Channels (Action Cable)
– Mailers (Action Mailer)
- Database (PostgreSQL or MySQL)
- Cache/Session store (Redis or Memcached)
- Background queue (Redis + Sidekiq or similar)
- File storage (local disk or external S3)
- External SMTP service
b. Relationships and interactions
- Browser sends HTTP(S) requests → Puma → Rails router → Controller actions.
- Controllers read/write via ActiveRecord to DB.
- Controllers render HTML/JSON via Views and serve assets.
- Stimulus controllers in browser communicate back via AJAX/WebSockets.
- Background tasks enqueued by ActiveJob → Queue backend (Redis) → Worker process.
- Action Cable connection established over WebSocket, handled by the same Rails process or separate server.
- File uploads posted to Rails → Active Storage → local disk or S3.
- Action Mailer sends messages via SMTP service.
c. Architectural patterns in use
- Layered MVC.
- Event-driven async processing (jobs, channels).
- Asset pipeline with importmap for JS modules.
- Convention-over-configuration.
d. Key technologies/frameworks
- Ruby 3.x, Rails 7
- Puma
- Sprockets & Importmap
- Stimulus (via importmap-rails)
- ActiveRecord + PostgreSQL/MySQL
- Active Job + Sidekiq/Resque
- Action Cable
- Active Storage
- Action Mailer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend
    Browser["Browser"]:::frontend

    %% Rails App
    subgraph "Rails App" 
        direction TB
        WebServer["Web Server (Puma)"]:::app
        Router["Router & Middleware Stack"]:::app
        Controllers["Controllers"]:::app
        Views["Views & Template Rendering"]:::app
        AssetPipeline["Asset Pipeline & Frontend"]:::app
        Models["Models (ActiveRecord)"]:::app
        Jobs["Background Jobs (ActiveJob)"]:::app
        Channels["WebSocket Channels (Action Cable)"]:::app
        Mailers["Mailers (Action Mailer)"]:::app
        StorageComp["Active Storage (File Uploads)"]:::app
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        DB["Database (PostgreSQL/MySQL)"]:::data
        Cache["Cache/Session Store (Redis)"]:::data
        Queue["Background Queue (Redis)"]:::data
        FileStore["File Storage (Disk/S3)"]:::data
        SMTP["SMTP Service"]:::external
    end

    %% Flows
    Browser -->|"HTTP/HTTPS"| WebServer
    WebServer -->|"Rack Request"| Router
    Router -->|"dispatch"| Controllers
    Controllers -->|"render"| Views
    Views -->|"HTML/JSON"| Browser

    Browser -->|"requests assets"| AssetPipeline
    AssetPipeline -->|"serve assets"| Browser

    Controllers -->|"ActiveRecord queries"| Models
    Models -->|"SQL"| DB

    Controllers -->|"enqueue job"| Jobs
    Jobs -->|"jobs"| Queue

    Controllers -->|"file upload"| StorageComp
    StorageComp -->|"store files"| FileStore

    Controllers -->|"send email"| Mailers
    Mailers -->|"SMTP"| SMTP

    Browser -->|"WebSocket"| Channels
    Channels -->|"pub/sub"| Cache

    %% Click Events
    click WebServer "https://github.com/cpeggy/cl3/blob/main/config/puma.rb"
    click WebServer "https://github.com/cpeggy/cl3/blob/main/config.ru"
    click WebServer "https://github.com/cpeggy/cl3/tree/main/bin/rails"
    click Router "https://github.com/cpeggy/cl3/blob/main/config/routes.rb"
    click Router "https://github.com/cpeggy/cl3/blob/main/config/application.rb"
    click Controllers "https://github.com/cpeggy/cl3/tree/main/app/controllers/"
    click Views "https://github.com/cpeggy/cl3/blob/main/app/views/layouts/application.html.erb"
    click AssetPipeline "https://github.com/cpeggy/cl3/blob/main/app/javascript/application.js"
    click AssetPipeline "https://github.com/cpeggy/cl3/blob/main/config/importmap.rb"
    click Models "https://github.com/cpeggy/cl3/tree/main/app/models/"
    click Jobs "https://github.com/cpeggy/cl3/tree/main/app/jobs/"
    click Channels "https://github.com/cpeggy/cl3/tree/main/app/channels/"
    click Mailers "https://github.com/cpeggy/cl3/tree/main/app/mailers/"
    click StorageComp "https://github.com/cpeggy/cl3/blob/main/config/storage.yml"

    %% Styles
    classDef frontend fill:#ccffcc,stroke:#339933,stroke-width:1px
    classDef app fill:#cce5ff,stroke:#3366cc,stroke-width:1px
    classDef data fill:#ffe5cc,stroke:#cc6600,stroke-width:1px
    classDef external fill:#f2f2f2,stroke:#999999,stroke-width:1px
```
