activeadmin-graphql 0.1.0

data/docs/graphql-api.md

@@ -0,0 +1,486 @@
+# GraphQL API
+
+This guide documents the [activeadmin-graphql](https://github.com/amkisko/activeadmin-graphql) gem: an optional GraphQL HTTP API for each ActiveAdmin namespace, built with [graphql-ruby](https://graphql-ruby.org/). The API mirrors the same resources, scoping, and controller behavior as the HTML and JSON admin endpoints: Ransack `q`, menu `scope`, sort `order`, nested `belongs_to` parents, CRUD, batch actions, and custom member and collection actions.
+
+The HTTP feature is off until you set `graphql = true` on a namespace. That adds a `POST` endpoint only (for example `POST /admin/graphql` for the default `admin` namespace); it does not replace the existing admin UI.
+
+## Gem and loading
+
+Add the extension to your application (it pulls in `activeadmin` and `graphql` as runtime dependencies):
+
+```ruby
+# Gemfile
+gem "activeadmin"
+gem "activeadmin-graphql"
+```
+
+Bundling loads `activeadmin/graphql`, which installs the Router/Resource integration and calls `ActiveAdmin::GraphQL.load!`, so graphql-ruby is loaded at boot whenever the gem is in your bundle. The schema class for a namespace is built on demand (first request or introspection) via `ActiveAdmin::GraphQL.schema_for(namespace)`.
+
+If `graphql = true` is set for a namespace but Bundler cannot satisfy the `graphql` gem, boot fails with an ActiveAdmin dependency error until you run `bundle install`.
+
+Custom pages that declare `graphql_field` with types such as `GraphQL::Types::Int` need graphql-ruby loaded before `app/admin` is evaluated; with `activeadmin-graphql` in the Gemfile that is already true.
+
+## Enabling the endpoint
+
+In `config/initializers/active_admin.rb`, turn on GraphQL for the namespace you
+want:
+
+```ruby
+ActiveAdmin.setup do |config|
+  config.namespace :admin do |admin|
+    admin.graphql = true
+    # Optional — default is "graphql", i.e. POST /admin/graphql
+    # admin.graphql_path = "graphql"
+  end
+end
+```
+
+Run `bin/rails active_admin:install` or reload routes if needed so
+`ActiveAdmin.routes(self)` is applied.
+
+### Namespace settings
+
+Each namespace inherits these options (defaults in parentheses):
+
+* `graphql` — set to `true` to mount the endpoint (`false` by default).
+* `graphql_path` — path segment under the namespace mount (`"graphql"`).
+* `graphql_multiplex_max` — maximum operations per multiplexed JSON array
+  request (`20`).
+* `graphql_max_complexity` — passed to graphql-ruby `max_complexity` when set.
+* `graphql_max_depth` — passed to `max_depth` when set.
+* `graphql_default_page_size` / `graphql_default_max_page_size` — connection
+  defaults when set.
+* `graphql_dataloader` — graphql-ruby dataloader plugin (`nil` = use
+  `GraphQL::Dataloader`). Set to `GraphQL::Dataloader::AsyncDataloader` when
+  the [`async` gem](https://github.com/socketry/async) is loaded if you want
+  parallel I/O from custom `GraphQL::Dataloader::Source` `#fetch` methods.
+* `graphql_visibility` — `nil` by default (no graphql-ruby visibility plugin).
+  Set to `true` to use [`GraphQL::Schema::Visibility`](https://graphql-ruby.org/schema/visibility.html)
+  with default options, or pass a `Hash` of visibility options (`profiles:`,
+  `dynamic:`, `preload:`, `migration_errors:`, …).
+* `graphql_visibility_profile` — when using named visibility profiles, optional
+  default `context[:visibility_profile]` for each HTTP request (symbols accepted).
+* `graphql_schema_visible` — optional `Proc` `(context, meta) -> Boolean` when
+  `graphql_visibility` is enabled; see Schema visibility below.
+* `graphql_configure_schema` — `Proc` receiving the schema class after build
+  (extensions, extra types, and so on).
+
+### GraphQL::Dataloader
+
+The namespace schema calls `schema.use` with the configured dataloader (see
+`graphql_dataloader` above). [graphql-ruby’s
+dataloader](https://graphql-ruby.org/dataloader/overview.html) batches external
+work across sibling fields using Fibers; each HTTP request gets its own
+dataloader instance (available as `context.dataloader` inside resolvers).
+
+Active Admin registers `ActiveAdmin::GraphQL::RecordSource` for
+non-polymorphic `belongs_to` columns on resource types: resolving `author { id }` on
+many `Post` nodes issues one batched `WHERE id IN (...)` for the related model
+instead of one query per node. Custom `graphql` `configure` fields and
+`register_page` `graphql_field` blocks run as normal GraphQL field methods, so
+you can use `dataloader` (or `context.dataloader`) with your own
+`GraphQL::Dataloader::Source` subclasses the same way as in standalone
+graphql-ruby apps.
+
+To implement `Schema.object_from_id` with batching (for example for `loads:` on
+mutation arguments), use `context.dataloader.with(ActiveAdmin::GraphQL::RecordSource, model_class).load(database_id)` inside your `graphql_configure_schema`
+hook after assigning `schema.define_singleton_method(:object_from_id, ...)`.
+Global / Relay-style IDs are not generated by Active Admin itself.
+
+### Schema visibility (`GraphQL::Schema::Visibility`)
+
+When `graphql_visibility` is set, the namespace schema calls
+`schema.use(GraphQL::Schema::Visibility, …)` so introspection and validation
+respect [visibility](https://graphql-ruby.org/schema/visibility.html).
+
+Set `graphql_schema_visible` to a proc that receives the GraphQL `context`
+and a `meta` hash and returns truthy to keep the member visible. The hash
+always includes `:kind`, and often `:graphql_type_name` (the resource’s GraphQL
+basename), `:resource` (`ActiveAdmin::Resource`), and other keys:
+
+| `kind` | Meaning |
+|--------|---------|
+| `:resource_interface` | `ActiveAdminResource` interface |
+| `:resource_object` | Resource object type |
+| `:resource_enum` | Rails enum type; `meta` includes `:column` |
+| `:input_object` | Create/update/where/list-filter input; `meta` includes `:role` (`:create_input`, …) |
+| `:registered_resource_union` | `ActiveAdminRegisteredResource` union |
+| `:run_action_payload` | Batch/member/collection action payload type |
+| `:query_registered_resource` | `registered_resource` query field |
+| `:query_collection_field` / `:query_member_field` | Resource list/detail fields; `meta` includes `:field_name` |
+| `:query_page_field` | Custom `register_page` field; `meta` includes `:page` |
+| `:mutation_create`, `:mutation_update`, `:mutation_delete`, … | CRUD and action mutations |
+
+Root `Query` / `Mutation` fields are defined with
+`ActiveAdmin::GraphQL::SchemaField`, which supports a `visibility:` keyword:
+a metadata `Hash` (same shape as the `meta` argument above) for
+`graphql_schema_visible`, not a graphql-ruby core option. Resource `graphql`
+`configure` blocks use that field class too, so custom fields may pass
+`visibility: { … }` when you want the hook to run.
+
+You can also subclass your own `GraphQL::Schema::Object` / `Field` types in
+`graphql_configure_schema` and implement `visible?` there; Active Admin’s
+helpers call `super` first so those implementations compose.
+
+Interfaces and unions: graphql-ruby may keep an interface or union visible
+when all members are hidden unless you return `false` from
+`graphql_schema_visible` for `:resource_interface` or `:registered_resource_union`
+(or implement `.visible?` on custom types). See graphql-ruby’s visibility migration
+notes for edge cases.
+
+## Making requests
+
+The endpoint accepts `POST` at `{namespace}/{graphql_path}` (for example
+`/admin/graphql`).
+
+Send JSON with `query` and optional `variables`. For
+[multiplexing](https://graphql-ruby.org/queries/multiplex.html), the body may
+be a JSON array of such objects; the size is limited by `graphql_multiplex_max`.
+
+Requests are handled by `ActiveAdmin::GraphqlController` (an engine controller,
+not a generated `Admin::…` subclass).
+
+### CSRF and cookie sessions
+
+`GraphqlController` uses Rails’ default CSRF protection
+(`protect_from_forgery with: :exception`). Clients that rely on session cookies
+(for example a typical Devise session) must submit a valid CSRF token with each
+`POST`, such as the `authenticity_token` used by the HTML admin. API-style
+clients often use header-based authentication without cookie sessions, or a
+separate route with CSRF disabled. Treat this endpoint like any other
+`ActionController::Base` `POST` from the browser.
+
+### Authentication and introspection
+
+The namespace `authentication_method` runs before any GraphQL work, including
+schema introspection. Unauthenticated clients should not receive a schema.
+
+The GraphQL context exposes the same user as `current_active_admin_user` (from
+the namespace `current_user_method`), wrapped for authorization checks.
+
+## Authorization
+
+Field resolvers call the namespace `authorization_adapter` (`authorized?` and
+`scope_collection`) for standard read and CRUD operations. Data loading reuses
+`ResourceController` (`find_collection`, `find_resource`,
+`apply_authorization_scope`, and related methods), so collection scoping matches
+REST.
+
+Batch, member, and collection mutations first require read access to the
+resource model (`authorized?` with the model class, in the same way as
+collection queries). They then run the same controller actions and blocks as the
+UI, including any `authorize!` or `authorize_resource!` calls.
+
+See the ActiveAdmin guide [Authorization adapter](https://activeadmin.info/13-authorization-adapter) for adapter setup; the same rules apply to GraphQL.
+
+## Schema overview
+
+The `Query` type includes one Relay-style connection field per resource route
+(for example `posts`), plus a singular field for a single record (for example
+`post`). Optional `graphql_field` entries on `register_page` appear here too,
+plus `registered_resource` (returning the `ActiveAdminRegisteredResource` union)
+when at least one resource is exposed.
+
+Every resource object type implements the `ActiveAdminResource` interface
+(`id: ID!`) so clients can share fragments or rely on a common shape.
+
+The `Mutation` type is present when at least one operation exists: per-resource
+`create_*`, `update_*`, and `delete_*` when those controller actions exist, plus
+`*_batch_action`, `*_member_action`, and `*_collection_action` fields when the
+resource defines the corresponding batch, member, or collection actions.
+
+Object type names default to the model name (for example `Post`). Typed input
+objects mirror `attributes_for_graphql` (see the per-resource section below):
+`PostCreateInput`, `PostUpdateInput`, `PostListFilterInput`, and `PostWhereInput`
+when the GraphQL name is `Post`.
+
+### Composite primary keys (Rails 7.1+)
+
+For models with `self.primary_key = [:book_code, :seq]` (and no separate `id`
+column), Active Admin treats GraphQL as follows:
+
+* `id` on the object type — JSON object string with all key columns in
+  model order (same format Rails uses when casting composite ids), for example
+  `{"book_code":"CPK","seq":7}`.
+* Readable fields — each primary-key column is also exposed as its own field
+  (in addition to `id`) so clients can load scalars without parsing JSON.
+* `LibraryEditionWhereInput` (and similar) — either optional `id` (that JSON
+  string) or every primary-key column; `id` remains required when there is
+  only one key column.
+* Singular query field — pass the JSON `id`, pass `where`, or pass one
+  GraphQL argument per primary-key column.
+* Create mutations — composite key attributes stay included in create
+  inputs (unlike single `id` tables, where the key is omitted from assignable
+  attributes).
+
+For REST/HTML member routes, `ResourceController#find_resource` must resolve composite ids from `params[:id]` (JSON string) or from individual primary-key params. Stock ActiveAdmin 3.x only passes a single `params[:id]` into `find`; an ActiveAdmin fork (or patch) that implements composite-aware `find_resource` keeps the admin UI aligned with GraphQL. The GraphQL layer also works with `ActiveAdmin::GraphQL::ResourceQueryProxy` using Rails’ tuple id convention for `Relation#find`.
+
+The gem ships `ActiveAdmin::PrimaryKey` when the core constant is missing (upstream). A fork may define `PrimaryKey` and extended `find_resource` in `ResourceController` instead.
+
+`ActiveAdmin::GraphQL::RecordSource` batch-loads composite associations using
+Rails `where(primary_key => [tuple, …])`.
+
+### Collection query arguments
+
+These align with REST index parameters where possible:
+
+* `filter` — optional `PostListFilterInput` with `scope`, `order`, `q` (Ransack
+  predicates as JSON — kept as JSON because predicate keys are open-ended), and the nested parent id when `belongs_to` applies.
+* `scope` — menu scope id (string); still accepted on the field for backward
+  compatibility.
+* `q` — Ransack predicates (JSON object).
+* `order` — index sort string (for example `id_desc`).
+* Parent foreign key — when the resource uses `belongs_to`, the parent param
+  (for example `user_id`) stays available on the connection field as today.
+
+### Singular query arguments
+
+* `where` — `PostWhereInput` with required `id` (single-key tables) or,
+  for composite keys, `id` (JSON) and/or each key column; optional parent ids for
+  nested resources.
+* Legacy `id` / parent arguments behave as before (composite models also accept
+  one argument per key column on the field itself).
+
+### CRUD mutations
+
+Typical names for a `Post` resource:
+
+* `create_post(input: PostCreateInput!)` — attribute fields match assignable
+  columns (and the nested parent param when `belongs_to` is configured).
+* `update_post(where: PostWhereInput!, input: PostUpdateInput!)`
+* `delete_post(where: PostWhereInput!)`
+
+Nested resources require the parent id on `where`, `input`, or list `filter`
+when the association is required.
+
+### Migrating GraphQL clients
+
+If you are updating clients that targeted an older embedded GraphQL integration (or regenerated types against a previous schema), check the following:
+
+* Rails enum GraphQL names use an `Enum` infix (for example `PostEnumStatus`, not `PostStatus`). Update persisted operations, codegen, and fragments to match; see Rails enum columns below.
+
+* CRUD mutations use typed `input` and `where` arguments (`PostCreateInput`, `PostWhereInput`, …), not a single loose `attributes` JSON object and bare `id` on update/delete. List/detail fields may use `where` / `filter` input objects; legacy scalar arguments on fields are unchanged where still exposed.
+
+* `registered_resource(path: …)`, batch `inputs`, and member/collection `params` use `[ActiveAdminKeyValuePair!]` (a list of `{ key, value }` strings), not arbitrary JSON objects. Express maps as list items; duplicate keys keep the last value. Ransack `q` (on list `filter` / field args) stays a JSON object.
+
+These rules match the current schema described in this guide. The core `activeadmin` gem’s `UPGRADING.md` may only mention them if you use a fork that references this extension.
+
+### `registered_resource` query
+
+`registered_resource(type_name: String!, id: ID!, path: [ActiveAdminKeyValuePair!])`
+returns `ActiveAdminRegisteredResource`, the union of all resource object types in
+the namespace. Pass nested parent route params as ordered `path: [{ key: "user_id", value: "1" }, …]`
+(same keys as REST path segments). Resolve with inline fragments on concrete types.
+
+`ActiveAdminKeyValuePair` is `{ key: String!, value: String! }` — flat strings only, like query/form fields.
+
+### Batch, member, and collection actions
+
+For a route key of `posts`, fields look like:
+
+* `posts_batch_action(batch_action: String!, ids: [ID!]!, inputs: [ActiveAdminKeyValuePair!], …)` —
+  runs the registered batch action; `inputs` is converted to `batch_action_inputs` (flat key/value map)
+  like the HTML form. Omitted when batch actions are disabled or none are registered.
+* `posts_member_action(action: String!, id: ID!, params: [ActiveAdminKeyValuePair!], …)` —
+  aggregate field: pick the `member_action` by `action` string (same as today).
+* One GraphQL field per registered action — `{plural}_member_{action_name}` with
+  underscores (e.g. `posts_member_publish`, `posts_member_append_title_bang`): same
+  `id`, `params`, and parent ids as the aggregate field, without an `action:` argument.
+  Use `graphql { member_action_mutation(:publish) { … } }` to set return type,
+  `resolve`, and extra `arguments { … }` for that action only.
+* `posts_collection_action(action: String!, params: [ActiveAdminKeyValuePair!], …)` —
+  aggregate collection actions by name.
+* Per collection action: `{plural}_collection_{action_name}` (e.g.
+  `posts_collection_posts_count`). Configure with `collection_action_mutation(:posts_count) { … }`.
+
+Action names are validated against registered definitions; arbitrary controller
+methods are not exposed.
+
+The aggregate fields stay available for clients that prefer a single entry point;
+per-action fields give distinct GraphQL input and output types per `member_action` /
+`collection_action` when you need them.
+
+By default, run-action mutations return `ActiveAdminRunActionPayload`: `ok`,
+`status`, `location` (redirects), and `body` (rendered output when present). You
+can replace that object type per resource (see Run action return types
+below). Resolvers still build `ActiveAdmin::GraphQL::RunActionPayload::Result`;
+custom types should usually subclass `RunActionPayload` so those fields keep
+working and `graphql_schema_visible` `:run_action_payload` continues to apply.
+
+## Per-resource `graphql` block
+
+Inside `ActiveAdmin.register` you can narrow the GraphQL surface:
+
+```ruby
+ActiveAdmin.register Post do
+  graphql do
+    disable!                          # omit this resource from the schema
+    type_name "BlogPost"              # GraphQL object / mutation type basename
+    only :title, :body, :published_at # expose only these attributes
+    exclude :internal_score           # or `except` / `exclude`
+    configure do
+      # graphql-ruby field DSL on the object type class
+      field :computed, GraphQL::Types::String, null: true
+      define_method(:computed) { object.title&.reverse }
+    end
+  end
+end
+```
+
+* `disable!` — resource is not included in Query or Mutation.
+* `type_name` — overrides the default GraphQL type name derived from the model
+  (object types, mutations, and Rails enum GraphQL types use this basename).
+* `only` / `except` (or `exclude`) — restrict columns on object types and
+  assignable mutation keys (the primary key remains readable as `id`).
+* `configure` — `field` and resolver methods are evaluated on the generated
+  object type class.
+
+### Run action return types (batch / member / collection mutations)
+
+Return type and optional resolver for each kind live together on
+`ActiveAdmin::GraphQL::RunActionMutationConfig` (`payload_type`, `resolve_proc`),
+exposed through the DSL in a graphql-ruby-like way.
+
+Use a `GraphQL::Schema::Object` subclass — typically subclass
+`ActiveAdmin::GraphQL::RunActionPayload` — then add fields and resolver methods.
+The mutation object passed to field methods is always
+`RunActionPayload::Result` (`ok`, `status`, `location`, `body`).
+
+Grouped (recommended):
+
+```ruby
+graphql do
+  run_action_payload_type(AppDefaultRunPayload) # optional default for all three kinds
+
+  batch_action_mutation do
+    type(Batches::BatchRunPayload)
+    resolve do |proxy:, batch_action:, ids:, inputs:, **kw|
+      # optional; same keyword args as resolve_batch_action
+      proxy.run_batch_action(batch_action, ids, inputs: inputs)
+    end
+  end
+
+  member_action_mutation do
+    type(Members::MemberRunPayload)
+  end
+
+  member_action_mutation(:send_invoice) do
+    type(Members::SendInvoicePayload)
+    arguments do
+      argument :note, GraphQL::Types::String, required: false, camelize: false
+    end
+  end
+end
+```
+
+Call the named field as `posts_member_send_invoice(id: "...", note: "…")`. Extra
+arguments are merged with `params` for the controller and passed as keyword args
+to a custom `resolve` block.
+
+With no symbol argument, `member_action_mutation { … }` configures only the
+aggregate `posts_member_action` field. With a symbol, it configures the
+per-action field `posts_member_<name>`.
+
+Inside each `*_mutation` block, `type` (alias `payload_type`) sets the GraphQL
+object type and `resolve` replaces the Ruby body for that field only. You can
+set just `type`, just `resolve`, or both; order inside the block does not matter.
+
+One-shot aliases (same underlying config):
+
+| DSL method | Effect |
+|------------|--------|
+| `run_action_payload_type(MyType)` | Default return type when a kind-specific `type` is not set. |
+| `batch_action_run_action_payload_type(MyType)` | Same as `batch_action_mutation { type(MyType) }`. |
+| `member_action_run_action_payload_type(MyType)` | Same as `member_action_mutation { type(MyType) }`. |
+| `collection_action_run_action_payload_type(MyType)` | Same as `collection_action_mutation { type(MyType) }`. |
+| `resolve_batch_action { … }` | Same as `batch_action_mutation { resolve { … } }` (and likewise for member/collection). |
+
+Per-kind `type` wins over `run_action_payload_type`; any unset kind falls back
+to `run_action_payload_type`, then `ActiveAdminRunActionPayload`. Set
+`graphql_name` on your subclass so introspection names stay stable.
+
+Per action name: use `member_action_mutation(:action_name)` /
+`collection_action_mutation(:action_name)` so each Registered action gets its
+own mutation field, return type, resolver, and optional `arguments` block. The
+aggregate `posts_member_action` / `posts_collection_action` fields remain for
+backwards compatibility and for resources that do not need per-action typing.
+
+### Resolver overrides (`resolve_*`)
+
+Field names and GraphQL types stay defined by Active Admin; these procs only
+replace the Ruby body that loads data or runs a mutation (similar in spirit to
+overriding `find_resource` / `find_collection` rather than inventing new field
+names):
+
+| DSL method | Replaces default … |
+|------------|-------------------|
+| `resolve_index` (alias `resolve_collection`) | List connection resolver; must return an `ActiveRecord::Relation` (or compatible). Receives `proxy`, `context`, `auth`, `aa_resource`, `graph_params`, and the list field arguments (`filter`, `scope`, `q`, `order`, parent ids, …). |
+| `resolve_show` (alias `resolve_member`) | Singular field and `registered_resource` for this resource; must return a record or `nil`. Receives `proxy`, `id`, `graph_params`, and for the generated `post` field also `where` / `id_argument` when present. |
+| `resolve_create` | After class-level create authorization: build and persist. Receives `proxy`, `input`, `attributes` (assignable slice), `context`, `auth`, `aa_resource`. Must return the created record; instance-level `authorized?` runs afterward. |
+| `resolve_update` | After load and update authorization: apply changes. Receives `record`, `input`, `attributes`, plus `proxy`, `context`, `auth`, `aa_resource`. Must return the updated record. |
+| `resolve_destroy` | After destroy authorization: delete or archive. Receives `record`, `proxy`, `context`, `auth`, `aa_resource`. Default is `record.destroy!`. |
+| `resolve_batch_action` | Batch mutation; receives `batch_action`, `ids`, `inputs` (string-key `Hash` after converting GraphQL key/value list), `proxy`, … Default calls `ResourceQueryProxy#run_batch_action`. |
+| `resolve_member_action` | Member-action mutation; receives `action`, `id`, `params` (string-key `Hash`), `proxy`, … |
+| `resolve_collection_action` | Collection-action mutation; receives `action`, `params` (string-key `Hash`), `proxy`, … |
+
+Standard authorization checks around each field or mutation still run; hooks
+are for customizing how data is fetched or saved, not for skipping policy.
+
+### Rails enum columns
+
+Attributes backed by `enum` (integer or string columns with `defined_enums`) are
+exposed as GraphQL enums. Each enum type is named
+
+`{GraphQLTypeBasename}Enum{ColumnNameInPascalCase}`
+
+where `GraphQLTypeBasename` is the resource’s GraphQL type name (from `type_name`
+or the model name), and `ColumnNameInPascalCase` is the database attribute in
+PascalCase (for example `notification_channel` → `NotificationChannel`).
+
+Examples:
+
+* `User` + column `notification_channel` → `UserEnumNotificationChannel`
+* `UserNotification` + column `channel` → `UserNotificationEnumChannel`
+
+Think of `PostEnumStatus` as the enum for `Post`’s `status` attribute, not as a
+single merged word like `PostStatus`. Putting `Enum` immediately after the
+resource basename (instead of a suffix such as `PostStatusEnum`) keeps the
+basename and column distinct when both are camelized. That avoids the duplicates
+graphql-ruby rejects when unrelated pairs would otherwise share one type name
+(for example joining basename and column with a single underscore and camelizing
+the whole string, or suffixing `Enum` after a fused `basename` + `column`
+string).
+
+If you still need to disambiguate or narrow the surface, you can:
+
+* set `type_name` on a resource so its enums get a different prefix;
+* use `only` / `except` to omit an enum attribute from GraphQL;
+* define a custom field in `configure` that uses your own shared enum type.
+
+## Custom pages
+
+`register_page` can add query fields:
+
+```ruby
+ActiveAdmin.register_page "Dashboard" do
+  graphql_field :open_tickets_count, GraphQL::Types::Int, null: false,
+                description: "Tickets still open" do |_user, _ctx|
+    Ticket.open.count
+  end
+end
+```
+
+The block receives `(current_user, context)`. Authorization uses the page as the
+subject for read access.
+
+## Custom schema class hook
+
+```ruby
+config.namespace :admin do |admin|
+  admin.graphql = true
+  admin.graphql_configure_schema = lambda do |schema|
+    # schema.max_complexity(...) etc. if not using namespace settings
+    # schema.use MyGraphQLExtension
+  end
+end
+```

data/lib/active_admin/graphql/auth_context.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module GraphQL
+    # Authorization adapter wrapper for GraphQL +context+.
+    class AuthContext
+      attr_reader :user, :namespace
+
+      def initialize(user:, namespace:)
+        @user = user
+        @namespace = namespace
+        @adapter_by_resource_id = {}
+      end
+
+      def adapter_for(aa_resource)
+        @adapter_by_resource_id[aa_resource.object_id] ||= begin
+          klass = namespace.authorization_adapter
+          klass = klass.constantize if klass.is_a?(String)
+          klass.new(aa_resource, user)
+        end
+      end
+
+      def authorized?(aa_resource, action, subject = nil)
+        adapter_for(aa_resource).authorized?(action, subject)
+      end
+
+      # Delegates to the namespace authorization adapter. Built-in resolvers scope
+      # collections through +ResourceController+ instead of calling this; it remains
+      # available for custom schema extensions or host-app glue code.
+      def scope_collection(aa_resource, relation, action = ActiveAdmin::Authorization::READ)
+        adapter_for(aa_resource).scope_collection(relation, action)
+      end
+    end
+  end
+end

data/lib/active_admin/graphql/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module GraphQL
+    class Engine < ::Rails::Engine
+      engine_name "activeadmin_graphql"
+    end
+  end
+end

data/lib/active_admin/graphql/integration.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "resource_definition_dsl"
+
+module ActiveAdmin
+  module GraphQL
+    # Hooks graphql configuration and routing into ActiveAdmin when this gem is loaded.
+    module Integration
+      module_function
+
+      def install!
+        return if @installed
+
+        @installed = true
+        ActiveAdmin::Application.prepend(ApplicationUnloadClearsGraphQLSchema)
+        register_namespace_settings!
+        ActiveAdmin::Resource.prepend(ResourceMethods)
+        ActiveAdmin::ResourceDSL.prepend(ResourceDSLMethods)
+        ActiveAdmin::Page.prepend(PageMethods)
+        ActiveAdmin::PageDSL.prepend(PageDSLMethods)
+        ActiveAdmin::Router.prepend(RouterMethods)
+        register_railtie!
+      end
+
+      def register_namespace_settings!
+        ns = ActiveAdmin::NamespaceSettings
+        ns.register :graphql, false
+        ns.register :graphql_path, "graphql"
+        ns.register :graphql_multiplex_max, 20
+        ns.register :graphql_dataloader, nil
+        ns.register :graphql_visibility, nil
+        ns.register :graphql_visibility_profile, nil
+        ns.register :graphql_schema_visible, nil
+        ns.register :graphql_max_complexity, nil
+        ns.register :graphql_max_depth, nil
+        ns.register :graphql_default_page_size, nil
+        ns.register :graphql_default_max_page_size, nil
+        ns.register :graphql_configure_schema, nil
+      end
+
+      def register_railtie!
+        return unless defined?(Rails::Railtie)
+
+        require_relative "railtie"
+      end
+
+      # Stale cached schemas keep references to resources/controllers cleared by +unload!+
+      # (e.g. specs that reload registrations). Always drop cached schema when AA unloads.
+      module ApplicationUnloadClearsGraphQLSchema
+        def unload!
+          super
+          ActiveAdmin::GraphQL.clear_schema_cache!
+        end
+      end
+
+      module ResourceMethods
+        def graphql_config
+          @graphql_config ||= ActiveAdmin::GraphQL::ResourceConfig.new
+        end
+
+        def attributes_for_graphql
+          keys = resource_attributes.keys
+          cfg = graphql_config
+          if cfg.only_attributes
+            keys &= cfg.only_attributes
+          end
+          keys -= cfg.exclude_attributes
+          keys
+        end
+
+        def graphql_assignable_attribute_names
+          names = attributes_for_graphql.map(&:to_s)
+          pk_cols = ActiveAdmin::PrimaryKey.columns(resource_class)
+          return names if pk_cols.size > 1
+
+          names - pk_cols
+        end
+      end
+
+      module ResourceDSLMethods
+        def graphql(&block)
+          if block
+            ActiveAdmin::GraphQL::ResourceDefinitionDSL.new(config.graphql_config).instance_exec(&block)
+          end
+          config.graphql_config
+        end
+      end
+
+      module PageMethods
+        def graphql_fields
+          @graphql_fields ||= []
+        end
+      end
+
+      module PageDSLMethods
+        def graphql_field(field_name, graphql_type, null: true, description: nil, &block)
+          config.graphql_fields << {
+            name: field_name.to_s,
+            type: graphql_type,
+            null: null,
+            description: description,
+            resolver: block
+          }
+        end
+      end
+
+      module RouterMethods
+        def apply
+          define_root_routes
+          define_graphql_routes
+          define_resources_routes
+        end
+
+        private
+
+        def define_graphql_routes
+          namespaces.each do |namespace|
+            next unless namespace.graphql
+
+            segment = namespace.graphql_path.to_s.delete_prefix("/").presence || "graphql"
+            defaults = {active_admin_namespace: namespace.name}
+
+            if namespace.root?
+              router.post segment, controller: "/active_admin/graphql", action: "execute", defaults: defaults
+            else
+              router.namespace namespace.name, **namespace.route_options.dup do
+                router.post segment, controller: "/active_admin/graphql", action: "execute", defaults: defaults
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end