Project Structure / Fullstack & API

The CLI generates a clean, modular project structure designed for Roda applications, prioritizing speed, maintainability, and clean architecture.

Below is a detailed breakdown of the files and directories in Fullstack and API project scaffolds.

Project Structure Overview

├── boot.rb
├── config.ru
├── esbuild.js          # (Fullstack only)
├── Gemfile
├── Guardfile
├── package.json        # (Fullstack only)
├── Rakefile
├── AGENTS.md
├── app/
│   ├── [project_name].rb
│   ├── assets/         # (Fullstack only)
│   ├── config/
│   │   ├── config.rb
│   │   ├── locales/
│   │   └── providers/
│   │       ├── db/
│   │       ├── logger.rb
│   │       └── mailer.rb
│   ├── models/
│   ├── routes/
│   └── views/          # (Fullstack only)
├── bin/
│   └── roda
├── db/
│   ├── migrations/
│   └── seeds.rb
├── public/
│   ├── assets/         # (Fullstack only)
│   ├── images/
│   └── exception_page.css
└── spec/
    ├── app/
    │   ├── models/
    │   └── routes/
    └── spec_helper.rb

Top-Level Files

  • boot.rb: The application startup bootstrapper. It sets up Bundler, initializes Zeitwerk code autoloading for application components, and loads service providers.
  • config.ru: The standard Rack configuration entrypoint. It configures Rack middleware (such as Rack::LiveReload in development) and mounts the primary Roda application.
  • esbuild.js: (Fullstack only) Configuration file for esbuild. Handles asset bundling (JavaScript and CSS) and outputs compiled bundles to public/assets/.
  • Gemfile: Defines Ruby gem dependencies partitioned by environment (development, test, production).
  • Guardfile: Configures Guard for watching application source code changes and triggering automatic reloads or spec executions.
  • package.json: (Fullstack only) Manages NPM dependencies for frontend tooling and client-side JavaScript packages.
  • bin/roda: The CLI executable tool embedded within your project for running servers, executing migrations, running linters, and scaffolding generators.
  • AGENTS.md: Contains project-specific rules and instructions for development guidelines and code conventions.

app/ Directory

Houses the core domain and routing logic of your Roda application:

  • app/<project_name>.rb: The main Roda application class. Configures Roda plugins, global middleware, error handlers, and top-level route routing.
  • app/assets/: (Fullstack only) Uncompiled frontend assets (CSS, JS) edited during development.
  • app/config/: Configuration management:
    • app/config/config.rb: Manages environment variables, application settings, database credentials, and secret keys.
    • app/config/locales/: Stores YAML internationalization (i18n) locale files (e.g. en.yml, pt-BR.yml).
    • app/config/providers/: Service provider initializers. A provider is a class used in the boot process for setup dependencies (or services) single instances and retrive in app logic.
  • app/models/: Sequel ORM model classes (e.g. account.rb).
  • app/routes/: Houses Roda hash branches. Each file defines sub-routes and endpoints for modular routing logic.
  • app/views/: (Fullstack only) Template directory:
    • .erb files: ERB template files for HTML rendering.
    • html.rb: Functional HTML component helpers and render helpers.

db/ Directory

Dedicated to database management and migrations:

  • db/migrations/: Sequel migration files prefixed with numeric sequence numbers (e.g. 001_add_rodauth.rb).
  • db/seeds.rb: Data seeding script for local development and testing environments.

public/ Directory

Contains static assets served directly by the web server or Rack static middleware:

  • public/assets/: Compiled frontend JavaScript and CSS bundles generated by esbuild.
  • public/images/: Static images and web icons.
  • public/exception_page.css: Styling used by Roda error pages in development mode.

spec/ Directory

Contains test suites (RSpec or Minitest):

  • spec/spec_helper.rb: Initializes the test helper environment, loads test dependencies (rack-test), and configures database rollback transactions around test specs.
  • spec/app/: Contains route, model, and application logic specs mirror-structured to the app/ folder.