How reallygoodsoftware/h1rails works
Project Overview
• This is a Ruby on Rails web application boilerplate designed to help both experienced Rails developers and beginners build polished web apps quickly.
• It’s “HTML First,” meaning that it emphasizes quick setup, no excessive client-side build tooling, and leverages static assets (CSS/JS) placed in the public folder.
• It comes with batteries-included support for common UI & UX patterns (modals, toasts, tooltips, type-to-search, etc.) and uses HTMX for interactivity instead of frameworks like Hotwire/Turbo.
Main Components
• Frontend/UI Layer:
• Views: Located in app/views, with subdirectories for standard application pages, admin-specific views, and demos (under h1rails/demos).
• Assets: Includes conventional Rails assets in app/assets (with stylesheets, JavaScript, images) plus public assets for CSS and JS libraries.
• Components & Partials: Separated into components (shared, h1rails/partials, shared partials) to implement various UI patterns.
• Documentation and demo pages (accessible under /demos as noted by the readme).
• Backend Layer:
• Controllers: Standard MVC controllers under app/controllers, including API controllers (namespaced under api/v1), user authentication controllers, h1rails demos, and streaming controllers.
• Models: Business logic and persistence are clearly represented in app/models with common Rails patterns. Specific models such as User, AdminUser, MessageTemplate, and Category are used.
• Jobs & Mailers: Background processing via jobs (app/jobs) and email notifications via mailers (app/mailers).
• Admin Interfaces: The app/admin folder and integration (via ActiveAdmin, as seen with ActiveAdmin initializer) provide the backend admin functionality.
• Configuration & Infrastructure:
• Config directory: Contains environment settings, routes in config/routes and custom routes for demos (h1_demo_routes.rb and h1_expo_routes.rb), initializers, and secrets.
• Database: Represented in db directory with migrations for Devise, Active Storage, and custom tables. There are explicit migration files (e.g., create_message_templates.rb, add_auth_token_to_users.rb).
• External Libraries & Tools: Includes configuration files like Gemfile, package.json, Tailwind config, and environment-specific files.
• Supporting Services & Utilities:
• Utility Scripts: Located under app/utils for miscellaneous helper functionalities.
• Documentation: Provided in the docs directory (and the single readme file) that further explains UI patterns, setup, and best practices.
Relationships and Interactions
• MVC Pattern: Clearly, the project follows the Rails Model-View-Controller pattern with direct interaction from controllers to models and views.
• API Layer: The API namespaces indicate a separation for web service interactions, potentially used by client-side JS or external integrations.
• Admin Integration: ActiveAdmin and admin-specific controllers/models indicate a management module that interacts with core user & data models.
• Asset and Static File Flow: The public folder houses unbundled CSS/JS assets that are directly loaded by the front end, reducing the need for build tooling.
• Routing & Configuration: Centralized routing (config/routes.rb and associated demo/expo routes) directs traffic amongst general app functionality, admin, and API endpoints.
• Utilization of HTMX: As documented, many UI interactions (like modal pop-ups and multistep forms) use HTMX for progressive enhancement, placing more logic in the HTML and server responses.
Final Steps for the Principal Software Engineer
• Gradually drill down to represent subcomponents (like API controllers, admin-specific flows, and static asset management).
• Use annotations to indicate important patterns such as the MVC design, modular routing, and integration with external libraries like HTMX and ActiveAdmin.