Rails monolith

The Ruby on Rails application that contains nearly all GitLab business logic. Served by Puma in production and by gdk start rails in development.

Purpose

Serve the GitLab web UI, REST and GraphQL APIs, OAuth/Doorkeeper endpoints, internal APIs (called by Workhorse, Shell, KAS, Pages), and the admin/observability endpoints.

Entry points

Concern	File
Rails boot	config/boot.rb, config/application.rb, config/environment.rb
Rack rackup	config.ru
Routes	config/routes.rb and config/routes/*.rb
Puma config	config/puma.rb.example, config/puma.example.development.rb
REST API root	lib/api/api.rb
GraphQL schema	app/graphql/gitlab_schema.rb
ActionCable mount	app/channels/application_cable/, cable.yml.example

Directory layout

app/
  assets/             # JS, CSS, images for the web UI
  channels/           # Action Cable channels
  components/         # ViewComponent components
  controllers/        # ~30 top-level controller groups
  events/             # Gitlab::EventStore event classes
  experiments/        # A/B experiments
  facades/            # Aggregating service-layer facades
  finders/            # ~46 read-only query objects
  graphql/            # GraphQL schema, types, mutations, resolvers
  helpers/            # Rails view helpers
  mailers/            # ActionMailer classes
  models/             # ~315 ActiveRecord model files
  policies/           # declarative_policy authorization rules
  presenters/         # PORO presenters wrapping models
  serializers/        # ActiveModel::Serializer classes for JSON
  services/           # ~130 service-object namespaces
  uploaders/          # CarrierWave uploaders for object storage
  validators/         # custom AR validators
  views/              # HAML templates
  workers/            # ~170 Sidekiq worker namespaces
ee/app/               # EE counterparts of the above
lib/                  # ~180 namespaces of platform code
  api/                # Grape REST API definitions
  gitlab/             # Gitlab:: namespace (massive)
config/               # Initializers, routes, environments
gems/                 # Monorepo gems loaded via path:

How a request flows

sequenceDiagram
    autonumber
    participant Browser
    participant WH as Workhorse
    participant Puma
    participant MW as Rack middleware
    participant Ctrl as Controller
    participant Pol as Policy
    participant Svc as Service
    participant DB as Postgres

    Browser->>WH: HTTP GET /group/project/-/issues
    WH->>Puma: forwarded request
    Puma->>MW: Rack stack (CORS, throttle, request_context, ...)
    MW->>Ctrl: dispatched route
    Ctrl->>Pol: can?(user, :read_project, project)
    Pol-->>Ctrl: true
    Ctrl->>Svc: IssuesFinder.new(...).execute
    Svc->>DB: SELECT ... (load-balanced)
    DB-->>Svc: rows
    Svc-->>Ctrl: ActiveRecord::Relation
    Ctrl-->>Puma: HAML rendered HTML
    Puma-->>WH: response
    WH-->>Browser: response (gzip, headers, ETag)

Highlights:

• The Rack middleware stack is assembled in config/application.rb plus dozens of initializers. Notable middleware: Gitlab::Middleware::ReadOnly, Gitlab::Middleware::PathTraversalCheck, Gitlab::Middleware::RailsQueueDuration, Gitlab::ApplicationContext, Gitlab::Middleware::Memory.
• Gitlab::ApplicationContext (lib/gitlab/application_context.rb) sets per-request log/trace metadata.
• Every controller declares feature_category. Many additionally declare urgency for SLI tagging via Gitlab::EndpointAttributes.
• Database connection routing happens transparently via gems/gitlab-database-load_balancing — reads go to replicas, writes go to the primary.

Key abstractions

Abstraction	File	Description
ApplicationController	app/controllers/application_controller.rb	Base for all controllers; auth, logging, feature flag checks
ApplicationRecord	app/models/application_record.rb	Base for main DB models
Ci::ApplicationRecord	app/models/ci/application_record.rb	Base for ci DB models
BaseService, BaseContainerService	app/services/base_service.rb, app/services/base_container_service.rb	Service-object roots
BasePolicy	app/policies/base_policy.rb	declarative_policy parent
ApplicationWorker	app/workers/concerns/application_worker.rb	Base for Sidekiq workers
Gitlab::EventStore	lib/gitlab/event_store.rb	Pub/sub built on Sidekiq
Gitlab::Auth	lib/gitlab/auth.rb (~22K lines context)	Token / OAuth / SSH key validation
Gitlab::GitalyClient	lib/gitaly_client.rb	gRPC client to Gitaly
API::API	lib/api/api.rb	Mounts the entire Grape REST API

EE additions

The EE tree under ee/app/ mirrors app/ and adds:

• ee/app/replicators/ — Geo replication abstractions.
• ee/app/policies/ — extra rules (e.g., audit, compliance, SCIM).
• Many service modules prepended onto FOSS counterparts via prepend_mod_with.

EE-specific business logic is lazily loaded only when Gitlab.ee? is true. The Gitlab::Ee boot module guards EE Rails initializers.

Notable subsystems mounted into the monolith

• GraphQL API (app/graphql/)
• REST API (lib/api/)
• Internal API (lib/api/internal/)
• Action Cable (app/channels/)
• Sidekiq workers (app/workers/)
• Banzai Markdown pipeline (lib/banzai/)
• Database — schema, migrations, load balancing
• Search — Elasticsearch + Zoekt + Active Context
• Feature flags
• Webhooks and Integrations

Where to start when modifying

• New page or REST endpoint: add a route, controller, service, finder, and tests.
• New worker: see Sidekiq jobs.
• New GraphQL field: see GraphQL API.
• New EE-only behavior: add to ee/app/ and prepend onto the FOSS class.
• New domain event: generate with bin/rails generate event ....

Related

• Architecture
• Patterns and conventions