# ikuromaira/spotlight architecture

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

- Interactive diagram: https://gitdiagram.com/ikuromaira/spotlight
- Repository: https://github.com/ikuromaira/spotlight

## Overview

##### Project type and purpose
- This is a monolithic, full-stack Ruby on Rails web application (“Spots”) for user-generated content (spots, tags, reviews, photos, collections).
- It serves HTML views, JSON endpoints (API for Stimulus controllers & PWA), real-time updates via Action Cable, background jobs (mailers, imports), and file storage.

##### High-level architecture & components
a. Clients
- Web browsers (HTML/CSS/JS via ERB templates & Stimulus controllers)
- PWA service worker / manifest
b. Rails Application (MVC)
- Controllers (HTTP & Action Cable)
- Models (ActiveRecord → Postgres)
- Views (ERB templates, JS/CSS assets via importmap & Tailwind)
c. Asset Pipeline & Frontend
- SCSS, Tailwind, DaisyUI compiled on build
- Stimulus controllers for client behavior (map interaction, autofill)
d. Data Store
- Relational DB (e.g. PostgreSQL via config/database.yml)
- Active Storage (local or cloud)
- Redis or internal queues (config/queue.yml) for background jobs
e. Background Processing
- ActiveJob (e.g. inline or Sidekiq) handling mailers, image processing
f. Real-time Layer
- Action Cable (websocket) for live updates
g. External services
- Mapbox (JS API)
- SMTP (password reset emails via PasswordsMailer)
- Third-party storage (S3, if configured)
h. Deployment & DevOps
- Docker (Dockerfile, .dockerignore)
- Kamal hooks for deploy lifecycle
- Procfile.dev & Foreman for local dev
- CI workflow (.github/workflows/ci.yml)

##### Diagramming the relationships
- Controllers talk to Models
- Postgres DB
- Active Storage subsystem
- Background Job queue (Redis or built-in)
- Pulls jobs from queue → runs mailers, processing jobs → may update DB or send emails
- Mapbox API
- SMTP server
- (Optionally) S3 or equivalent storage
- Deployment pipeline (on one side)
- Docker build → image deployed via Kamal → runs Puma & Sidekiq, assets precompiled
- CI/CD
- GitHub Actions → runs tests (Rake, System Test) → deploy on success

##### Architectural patterns & design principles
- MVC separation: keep models, views, controllers distinct.
- Client-side enhancements via Stimulus (progressive enhancement).
- Separation of real-time vs request/response paths (Action Cable vs HTTP).
- Assets managed via Rails asset pipeline + importmap + Tailwind.
- Background processing decoupled from web requests.
- Config-as-code for deployment (Kamal, Dockerfile, Procfile.dev).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Clients" 
        direction TB
        Browser["Web Browser\n(HTML/CSS/JS)"]:::frontend
        PWA["PWA Service Worker\n& Manifest"]:::frontend
        Stimulus["Stimulus Controllers"]:::frontend
    end

    Browser -->|HTTP/HTTPS| RailsServer
    Browser -->|WSS| ActionCable
    PWA -->|Intercepts Requests| Browser
    PWA -->|Uses| RailsServer

    subgraph "Rails Server (Puma)" 
        direction TB
        Router["Router\n(config/routes.rb)"]:::backend
        Controllers["HTTP & ActionCable Controllers"]:::backend
        ViewsAssets["Views & Assets"]:::backend
        Models["ActiveRecord Models"]:::backend
        Router -->|Routes Requests| Controllers
        Controllers -->|Render| ViewsAssets
        Controllers -->|Query| Models
        ViewsAssets -->|JS/CSS| Browser
    end

    RailsServer((Puma)):::backend
    RailsServer -->|dispatch| Router

    subgraph "Asset Pipeline & Frontend" 
        direction TB
        Importmap["Importmap\n(config/importmap.rb)"]:::frontend
        Tailwind["Tailwind & DaisyUI\n(app/assets/tailwind/)"]:::frontend
        JSApp["JS Entrypoint\n(app/javascript/application.js)"]:::frontend
    end

    ViewsAssets --> Importmap
    ViewsAssets --> Tailwind
    ViewsAssets --> JSApp

    subgraph "Real-time Layer" 
        direction TB
        ActionCable[(Action Cable)]:::backend
        Connection["Connection\n(app/channels/application_cable/connection.rb)"]:::backend
        CableConfig["Cable Config\n(config/cable.yml)"]:::backend
        ActionCable --> Connection
    end

    Controllers --> ActionCable

    subgraph "Data Store" 
        direction TB
        Postgres[(PostgreSQL)]:::database
        ActiveStorage[(Active Storage)]:::database
        Redis[(Queue/Cache)]:::database
        Models --> Postgres
        Models --> ActiveStorage
        Controllers --> Redis
    end

    subgraph "Background Worker" 
        direction TB
        Sidekiq["ActiveJob/Sidekiq"]:::backend
        Jobs["Jobs & Mailers"]:::backend
        QueueConfig["Queue Config\n(config/queue.yml)"]:::backend
        Sidekiq --> Jobs
        Sidekiq --> Postgres
        Jobs -->|send email| SMTP
    end

    Redis --> Sidekiq

    subgraph "External Services" 
        direction TB
        Mapbox["Mapbox API"]:::external
        SMTP["SMTP Email"]:::external
        S3["S3 Storage (Optional)"]:::external
        Controllers --> Mapbox
        Jobs --> SMTP
        ActiveStorage --> S3
    end

    subgraph "Deployment & DevOps" 
        direction TB
        Docker["Docker\n(Dockerfile)"]:::infra
        Kamal["Kamal Hooks\n(.kamal/hooks/)"]:::infra
        CI["GitHub Actions\n(.github/workflows/ci.yml)"]:::infra
        ProcDev["Procfile.dev"]:::infra
        Docker -->|build| RailsServer
        Kamal --> RailsServer
        CI -->|tests & deploy| Kamal
    end

    classDef frontend fill:#d0e7ff,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#d0ffd8,stroke:#28a745,color:#28a745;
    classDef database fill:#fff4d6,stroke:#dbab09,color:#dbab09,stroke-dasharray: 5 5;
    classDef external fill:#ffe4e1,stroke:#cb2431,color:#cb2431,stroke-dasharray: 2 2;
    classDef infra fill:#f0f0f0,stroke:#6a737d,color:#6a737d;

    click PWA "https://github.com/ikuromaira/spotlight/blob/main/app/views/pwa/service-worker.js"
    click PWA "https://github.com/ikuromaira/spotlight/blob/main/app/views/pwa/manifest.json.erb"
    click Stimulus "https://github.com/ikuromaira/spotlight/tree/main/app/javascript/controllers/"
    click Stimulus "https://github.com/ikuromaira/spotlight/blob/main/app/javascript/controllers/map_controller.js"
    click Stimulus "https://github.com/ikuromaira/spotlight/blob/main/app/javascript/controllers/autofill_search_address_controller.js"
    click Controllers "https://github.com/ikuromaira/spotlight/tree/main/app/controllers/"
    click Router "https://github.com/ikuromaira/spotlight/blob/main/config/routes.rb"
    click Connection "https://github.com/ikuromaira/spotlight/blob/main/app/channels/application_cable/connection.rb"
    click CableConfig "https://github.com/ikuromaira/spotlight/blob/main/config/cable.yml"
    click Models "https://github.com/ikuromaira/spotlight/tree/main/app/models/"
    click ViewsAssets "https://github.com/ikuromaira/spotlight/tree/main/app/views/"
    click Importmap "https://github.com/ikuromaira/spotlight/blob/main/config/importmap.rb"
    click Tailwind "https://github.com/ikuromaira/spotlight/blob/main/app/assets/tailwind/application.css"
    click JSApp "https://github.com/ikuromaira/spotlight/blob/main/app/javascript/application.js"
    click Jobs "https://github.com/ikuromaira/spotlight/blob/main/app/jobs/application_job.rb"
    click Jobs "https://github.com/ikuromaira/spotlight/blob/main/app/mailers/passwords_mailer.rb"
    click QueueConfig "https://github.com/ikuromaira/spotlight/blob/main/config/queue.yml"
    click Redis "https://github.com/ikuromaira/spotlight/blob/main/config/queue.yml"
    click Postgres "https://github.com/ikuromaira/spotlight/blob/main/config/database.yml"
    click ActiveStorage "https://github.com/ikuromaira/spotlight/blob/main/config/storage.yml"
    click Docker "https://github.com/ikuromaira/spotlight/tree/main/Dockerfile"
    click Kamal "https://github.com/ikuromaira/spotlight/tree/main/.kamal/hooks/"
    click CI "https://github.com/ikuromaira/spotlight/blob/main/.github/workflows/ci.yml"
    click ProcDev "https://github.com/ikuromaira/spotlight/blob/main/Procfile.dev"
```
