How ikuromaira/spotlight works
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).