ISS Rails Architecture

arch-rails Doc

architecture rails iss

Project

ISS Rails Architecture

Framework

Ruby on Rails 8 — full-stack monolith serving both the public landing page and the authenticated client management app. The same codebase powers the marketing site at intelligentstaffingsystems.ai and the iOS app via Turbo Native.

Asset Pipeline

Propshaft — Rails 8 default asset pipeline. No Sprockets, no Node build step. CSS is served from app/assets/stylesheets/. JavaScript uses import maps.

Mobile Delivery

Turbo Native — the iOS app wraps the Rails backend in a native shell. Interface changes deploy by pushing to Rails; no App Store resubmission required for UI updates. The companion iOS repo consumes the same endpoints and views.

Authentication

Keycloak OIDC — all authentication is handled by a self-hosted Keycloak instance. The Rails app is an OIDC relying party. Three roles are enforced: prospect, client, and admin. Session management flows through Keycloak; the app never stores passwords.

Testing

Minitest — endpoint-first controller tests with no system/browser tests. Keycloak sessions are stubbed per role in the test helper. Tests run inside Docker via docker compose run web rails test. CI gates PRs on the full test suite.

Development Environment

Docker-based — the web image is pulled from Harbor (no local Dockerfile build). Local dev runs via docker compose up on port 9999. Production runs on port 3000 per the platform port convention.

Key Directories

app/controllers/ — request handling; auth gating via before_action
app/views/ — ERB templates; tab-based navigation for the authenticated app
app/assets/stylesheets/ — Propshaft CSS (forms, pages, navigation)
config/routes.rb — route definitions; landing page, leads, dashboard, messaging
test/ — Minitest suite; controller tests stub Keycloak sessions