Convention: Rails Frontend Architecture

arch-rails-frontend Convention

architecture convention

Project

Convention: Rails Frontend Architecture

Governs the frontend layer of Rails platform apps: views, CSS, Turbo, Stimulus, and Turbo Native integration.

Rule

All frontend work uses server-rendered ERB with Turbo for navigation, CSS custom properties for theming (no CSS frameworks), inline SVG for icons/badges, and Turbo Native User-Agent detection for mobile-specific behavior. The landing page is web-only; authenticated UI uses the .bottom-nav tab layout.

Rationale

A single rendering model (server ERB + Turbo) keeps the stack simple for a solo operator. No build step, no JS framework, no asset pipeline complexity. Turbo Native wraps the same server-rendered views for iOS/Android, so one codebase serves all platforms. Inline SVG avoids CDN dependencies and CSP issues.

Examples

Correct	Incorrect	Why
Inline SVG in ERB partial	External CDN icon library	No external dependencies, works offline
CSS custom properties (<code>--color-accent</code>)	Bootstrap/Tailwind classes	Consistent theming, no framework lock-in
<code>.landing-*</code> class prefix for landing page	Generic class names	Scoped naming prevents style collisions
Turbo Native User-Agent check in controller	JS-based platform detection	Server decides routing before rendering

Enforcement

Convention only. Enforced by code review and ticket scope review (skill-review-ticket).

project-landscaping-assistant — primary app using this architecture
convention-architecture-ids — architecture ID registry

Convention: Rails Frontend Architecture