ecoportal-api-graphql 2.0.0 → 2.2.1

data/lib/ecoportal/api/graphql/query/register_preview_pages.rb

@@ -1,83 +1,83 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Query
-        # Elasticsearch-backed fast search within a register.
-        # Returns PreviewPage nodes — no field IDs, no patchVer.
-        # Use for metadata lookup (find by externalId, state, location, date).
-        # Switch to Query::Pages (org search) for full data before mutations.
-        #
-        # Supports includeArchived: Boolean (default false).
-        # Supports presetViewId: ID to apply a register PageView preset.
-        class RegisterPreviewPages < Logic::QueryConnection
-          field_name :previewPages
-
-          accepted_params :registerId, :after, :before, :first, :last,
-                          :searchConf, :includeArchived, :presetViewId
-
-          class_resolver :item_class,       'Ecoportal::API::GraphQL::Model::PreviewPage'
-          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::PreviewPage'
-
-          def path
-            %w[currentOrganization register previewPages]
-          end
-
-          private
-
-          def basic_block(&block)
-            connection_block = block || default_connection_block
-            proc {
-              query(
-                registerId:      :id!,
-                after:           :string,
-                before:          :string,
-                first:           :int,
-                last:            :int,
-                searchConf:      :Search,
-                includeArchived: :boolean,
-                presetViewId:    :id
-              ) {
-                currentOrganization {
-                  register(id: :registerId) {
-                    previewPages(
-                      after:           :after,
-                      before:          :before,
-                      first:           :first,
-                      last:            :last,
-                      searchConf:      :searchConf,
-                      includeArchived: :includeArchived,
-                      presetViewId:    :presetViewId,
-                      &connection_block
-                    )
-                  }
-                }
-              }
-            }
-          end
-
-          def default_connection_block
-            proc {
-              totalCount
-              pageInfo {
-                endCursor
-                hasNextPage
-              }
-              nodes {
-                id
-                uid
-                name
-                state
-                archived
-                externalId
-                creatorName
-                createdAt { dateTime timeZone }
-                updatedAt { dateTime timeZone }
-                locations { id name }
-              }
-            }
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # Elasticsearch-backed fast search within a register.
+        # Returns PreviewPage nodes — no field IDs, no patchVer.
+        # Use for metadata lookup (find by externalId, state, location, date).
+        # Switch to Query::Pages (org search) for full data before mutations.
+        #
+        # Supports includeArchived: Boolean (default false).
+        # Supports presetViewId: ID to apply a register PageView preset.
+        class RegisterPreviewPages < Logic::QueryConnection
+          field_name :previewPages
+
+          accepted_params :registerId, :after, :before, :first, :last,
+                          :searchConf, :includeArchived, :presetViewId
+
+          class_resolver :item_class,       'Ecoportal::API::GraphQL::Model::PreviewPage'
+          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::PreviewPage'
+
+          def path
+            %w[currentOrganization register previewPages]
+          end
+
+          private
+
+          def basic_block(&block)
+            connection_block = block || default_connection_block
+            proc {
+              query(
+                registerId:      :id!,
+                after:           :string,
+                before:          :string,
+                first:           :int,
+                last:            :int,
+                searchConf:      :Search,
+                includeArchived: :boolean,
+                presetViewId:    :id
+              ) {
+                currentOrganization {
+                  register(id: :registerId) {
+                    previewPages(
+                      after:           :after,
+                      before:          :before,
+                      first:           :first,
+                      last:            :last,
+                      searchConf:      :searchConf,
+                      includeArchived: :includeArchived,
+                      presetViewId:    :presetViewId,
+                      &connection_block
+                    )
+                  }
+                }
+              }
+            }
+          end
+
+          def default_connection_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                id
+                uid
+                name
+                state
+                archived
+                externalId
+                creatorName
+                createdAt { dateTime timeZone }
+                updatedAt { dateTime timeZone }
+                locations { id name }
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/query/template_change_log.rb

@@ -0,0 +1,118 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # TEMPLATE CHANGE LOG — "for template X, who changed what, and when", newest first,
+        # paginated.
+        #
+        # Read path (verified in the Rails backend on 2026-08-19):
+        #   currentOrganization.page(id:) → template → commands
+        # There is NO top-level query for the narrow `Template` type. `template` is declared on
+        # `app/graphql/types/pages/interfaces/base_page_interface.rb:27`, so it is reachable on
+        # any page — and a template IS a page in this platform, so pass the TEMPLATE's page id.
+        #
+        # `currentOrganization.page(id:)` returns a `PageUnion`, so `template` has to be selected
+        # through a type condition on `BasePageInterface` — selecting directly on a union is
+        # invalid GraphQL under any schema (this is the class of bug the `validate-queries` CI
+        # gate hard-fails on). The type condition does not change the response shape, so `#path`
+        # still digs currentOrganization → page → template → commands.
+        #
+        # ★ Access caveats and the forces watermark blind spot are documented on
+        # `Base::Template::ChangeLogEntry`. In short: a nil `commands` connection means the caller
+        # lacks `Pages::TemplatePolicy#update_information?`, NOT that nothing changed; and only
+        # TEMPLATE_BUILDER-sourced commands appear here (workflow-builder ones live on
+        # `Query::PagesWorkflowCommands`).
+        #
+        # Usage:
+        #   q = Query::TemplateChangeLog.new(client)
+        #   conn = q.query(id: template_page_id, first: 50)
+        #   conn.nodes.each { |e| puts "#{e.createdAt.dateTime} #{e.owner&.name} #{e.commandAction}" }
+        #
+        #   # auto-paginating enumerator (Logic::QueryConnection#each)
+        #   q.each(id: template_page_id, first: 100) { |entry| ... }
+        #
+        # Also reachable as `api.template.change_log(id:, first:)` — see `Builder::Template`.
+        #
+        # ★ For WHAT CHANGED (field/from/to, change messages) pass `detail: true` to the builder,
+        # or `&Query::TemplateChangeLog.detail_block` here. The default selection deliberately
+        # omits it so the common "who and when" read stays cheap.
+        class TemplateChangeLog < Logic::QueryConnection
+          SCHEMA_VERSION = '20260819'.freeze
+
+          field_name :commands
+
+          accepted_params :id, :after, :before, :first, :last
+
+          class_resolver :item_class,       'Ecoportal::API::GraphQL::Model::Template::ChangeLogEntry'
+          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::TemplateChangeLog'
+
+          # Absolute — the connection is nested three levels deep, so it is not expressible as
+          # `base_path + field_name`.
+          def path
+            %w[currentOrganization page template commands]
+          end
+
+          # Connection block that selects FIELD-LEVEL DETAIL as well -- what changed, not just
+          # who/when/which-resource. Opt-in, because it adds three inline fragments and their
+          # sub-selections to every node.
+          #
+          #   q = Query::TemplateChangeLog.new(client)
+          #   conn = q.query(id: template_page_id, first: 50, &described_class.detail_block)
+          #   conn.nodes.each do |e|
+          #     case e.detail_kind
+          #     when :changes         then e.changes.each { |c| puts "#{c['field']}: #{c['from']} -> #{c['to']}" }
+          #     when :change_messages then puts e.changeMessages.join('; ')
+          #     when :es_changes      then puts "filter changed: #{e.changes.map { |c| c['field'] }.join(', ')}"
+          #     end
+          #   end
+          #
+          # Or simply `api.template.change_log(id:, first:, detail: true)`.
+          def self.detail_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                spread :TemplateChangeLogEntryDetail
+              }
+            }
+          end
+
+          private
+
+          def basic_block(&block)
+            connection_block = block || default_connection_block
+            proc {
+              query(id: :id!, after: :string, before: :string, first: :int, last: :int) {
+                currentOrganization {
+                  page(id: :id) {
+                    spread on: :BasePageInterface do
+                      template {
+                        commands(after: :after, before: :before, first: :first, last: :last, &connection_block)
+                      }
+                    end
+                  }
+                }
+              }
+            }
+          end
+
+          def default_connection_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                spread :TemplateChangeLogEntry
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/query/templates.rb

@@ -1,53 +1,53 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Query
-        class Templates < Logic::QueryConnection
-          field_name :templates
-
-          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PageUnion'
-          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::Page'
-
-          private
-
-          def basic_block(&block)
-            connection_block = block || default_connection_block
-            proc {
-              query(
-                searchConf: :Search,
-                after:      :string,
-                before:     :string,
-                first:      :int,
-                last:       :int
-              ) {
-                currentOrganization {
-                  templates(
-                    searchConf: :searchConf,
-                    after:      :after,
-                    before:     :before,
-                    first:      :first,
-                    last:       :last,
-                    &connection_block
-                  )
-                }
-              }
-            }
-          end
-
-          def default_connection_block
-            proc {
-              totalCount
-              pageInfo {
-                endCursor
-                hasNextPage
-              }
-              nodes {
-                spread :PageFields
-              }
-            }
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        class Templates < Logic::QueryConnection
+          field_name :templates
+
+          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PageUnion'
+          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::Page'
+
+          private
+
+          def basic_block(&block)
+            connection_block = block || default_connection_block
+            proc {
+              query(
+                searchConf: :Search,
+                after:      :string,
+                before:     :string,
+                first:      :int,
+                last:       :int
+              ) {
+                currentOrganization {
+                  templates(
+                    searchConf: :searchConf,
+                    after:      :after,
+                    before:     :before,
+                    first:      :first,
+                    last:       :last,
+                    &connection_block
+                  )
+                }
+              }
+            }
+          end
+
+          def default_connection_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                spread :PageFields
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/query.rb

@@ -19,6 +19,7 @@ require_relative 'query/page_activities'
 require_relative 'query/auth_logs'
 require_relative 'query/permissions'
 require_relative 'query/person_member_changelogs'
+require_relative 'query/person_members'
 require_relative 'query/dashboard_search'
 require_relative 'query/page'
 require_relative 'query/pages'
@@ -31,3 +32,4 @@ require_relative 'query/file_upload_signature'
 
 require_relative 'query/page_with_forces'
 require_relative 'query/pages_workflow_commands'
+require_relative 'query/template_change_log'

data/lib/ecoportal/api/graphql_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GRAPQL_VERSION = '2.0.0'.freeze
+    GRAPQL_VERSION = '2.2.1'.freeze
   end
 end

data/lib/ecoportal/api-graphql.rb

@@ -1,10 +1,10 @@
-require "ecoportal/api-v2"
-require "ecoportal/api/graphql_version"
-
-module Ecoportal
-  module API
-  end
-end
-
-require_relative "api/common.graphql"
-require_relative "api/graphql"
+require "ecoportal/api-v2"
+require "ecoportal/api/graphql_version"
+
+module Ecoportal
+  module API
+  end
+end
+
+require_relative "api/common.graphql"
+require_relative "api/graphql"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-graphql
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.1
 platform: ruby
 authors:
 - Oscar Segura
@@ -160,7 +160,7 @@ dependencies:
         version: '3.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.3.3
+        version: 3.3.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -170,7 +170,7 @@ dependencies:
         version: '3.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.3.3
+        version: 3.3.5
 - !ruby/object:Gem::Dependency
   name: graphlient
   requirement: !ruby/object:Gem::Requirement
@@ -203,14 +203,12 @@ files:
 - lib/ecoportal/api-graphql.rb
 - lib/ecoportal/api/common.graphql.rb
 - lib/ecoportal/api/common/graphql.rb
-- lib/ecoportal/api/common/graphql/CLAUDE.md
 - lib/ecoportal/api/common/graphql/auth_service.rb
 - lib/ecoportal/api/common/graphql/class_helpers.rb
 - lib/ecoportal/api/common/graphql/client.rb
 - lib/ecoportal/api/common/graphql/hash_helpers.rb
 - lib/ecoportal/api/common/graphql/http_client.rb
 - lib/ecoportal/api/common/graphql/model.rb
-- lib/ecoportal/api/common/graphql/model/CLAUDE.md
 - lib/ecoportal/api/common/graphql/model/as_input.rb
 - lib/ecoportal/api/common/graphql/model/diffable.rb
 - lib/ecoportal/api/common/graphql/model/diffable/classic_diff_service.rb
@@ -221,9 +219,7 @@ files:
 - lib/ecoportal/api/common/graphql/patches.rb
 - lib/ecoportal/api/common/graphql/query_integration.rb
 - lib/ecoportal/api/graphql.rb
-- lib/ecoportal/api/graphql/CLAUDE.md
 - lib/ecoportal/api/graphql/base.rb
-- lib/ecoportal/api/graphql/base/CLAUDE.md
 - lib/ecoportal/api/graphql/base/action.rb
 - lib/ecoportal/api/graphql/base/action_category.rb
 - lib/ecoportal/api/graphql/base/action_event.rb
@@ -316,8 +312,8 @@ files:
 - lib/ecoportal/api/graphql/base/register.rb
 - lib/ecoportal/api/graphql/base/resource.rb
 - lib/ecoportal/api/graphql/base/template.rb
+- lib/ecoportal/api/graphql/base/template/change_log_entry.rb
 - lib/ecoportal/api/graphql/builder.rb
-- lib/ecoportal/api/graphql/builder/CLAUDE.md
 - lib/ecoportal/api/graphql/builder/action.rb
 - lib/ecoportal/api/graphql/builder/contractor_entity.rb
 - lib/ecoportal/api/graphql/builder/kickstand.rb
@@ -358,6 +354,7 @@ files:
 - lib/ecoportal/api/graphql/connection/person_member_changelog.rb
 - lib/ecoportal/api/graphql/connection/preset_view.rb
 - lib/ecoportal/api/graphql/connection/preview_page.rb
+- lib/ecoportal/api/graphql/connection/template_change_log.rb
 - lib/ecoportal/api/graphql/diff.rb
 - lib/ecoportal/api/graphql/diff/change.rb
 - lib/ecoportal/api/graphql/diff/command_synthesizer.rb
@@ -400,6 +397,7 @@ files:
 - lib/ecoportal/api/graphql/fragment/permissions.rb
 - lib/ecoportal/api/graphql/fragment/person_member_changelog.rb
 - lib/ecoportal/api/graphql/fragment/template.rb
+- lib/ecoportal/api/graphql/fragment/template_change_log.rb
 - lib/ecoportal/api/graphql/helpers.rb
 - lib/ecoportal/api/graphql/helpers/locations_tree.rb
 - lib/ecoportal/api/graphql/input.rb
@@ -534,7 +532,9 @@ files:
 - lib/ecoportal/api/graphql/input/workflow_command/field_config/select.rb
 - lib/ecoportal/api/graphql/input/workflow_command/field_config/signature.rb
 - lib/ecoportal/api/graphql/input/workflow_command/field_config/table.rb
+- lib/ecoportal/api/graphql/input/workflow_command/manage_copy_page_configuration.rb
 - lib/ecoportal/api/graphql/input/workflow_command/move_field.rb
+- lib/ecoportal/api/graphql/input/workflow_command/move_section_to_stage.rb
 - lib/ecoportal/api/graphql/input/workflow_command/move_stage.rb
 - lib/ecoportal/api/graphql/input/workflow_command/move_viewable_field.rb
 - lib/ecoportal/api/graphql/input/workflow_command/remove_action_tag.rb
@@ -626,6 +626,7 @@ files:
 - lib/ecoportal/api/graphql/model/register.rb
 - lib/ecoportal/api/graphql/model/resource.rb
 - lib/ecoportal/api/graphql/model/template.rb
+- lib/ecoportal/api/graphql/model/template/change_log_entry.rb
 - lib/ecoportal/api/graphql/model/user.rb
 - lib/ecoportal/api/graphql/mutation.rb
 - lib/ecoportal/api/graphql/mutation/action.rb
@@ -764,8 +765,10 @@ files:
 - lib/ecoportal/api/graphql/query/pages_workflow_commands.rb
 - lib/ecoportal/api/graphql/query/permissions.rb
 - lib/ecoportal/api/graphql/query/person_member_changelogs.rb
+- lib/ecoportal/api/graphql/query/person_members.rb
 - lib/ecoportal/api/graphql/query/register_preset_views.rb
 - lib/ecoportal/api/graphql/query/register_preview_pages.rb
+- lib/ecoportal/api/graphql/query/template_change_log.rb
 - lib/ecoportal/api/graphql/query/templates.rb
 - lib/ecoportal/api/graphql_version.rb
 homepage: https://www.ecoportal.com

data/lib/ecoportal/api/common/graphql/CLAUDE.md

@@ -1,36 +0,0 @@
-# common/graphql
-
-Shared HTTP transport, authentication, and base model infrastructure used by the gem — nothing here is EcoPortal-domain-specific.
-
-## Contents
-
-| File / class | Purpose |
-|---|---|
-| `auth_service.rb` / `AuthService` | OAuth2 password + refresh-token flow; included in both client classes |
-| `client.rb` / `Client` | Graphlient-based GraphQL client (builds bearer-token headers, constructs endpoint URL) |
-| `http_client.rb` / `HttpClient` | Raw HTTP client (extends `Common::Client`); `execute` sends query strings + variables; supports v0–v3 + graphql API version modes |
-| `class_helpers.rb` / `ClassHelpers` | `becomes(klass)` instance casting + `const?` class helper |
-| `hash_helpers.rb` / `HashHelpers` | Deep key transforms (`keys_to_sym_deep`, `deep_dup`, `remove_nil_keys_deep`) — used by diff and input serialisation |
-| `query_integration.rb` / `QueryIntegration` | Class macro `query(:method, query_klass:)` that wires a named query method on `Model::Organization` |
-| `model.rb` / `Model` | Base model class: `DoubleModel` + `Diffable` + `AsInput`; all GraphQL models ultimately inherit this |
-| `patches.rb` | Reserved placeholder (empty) |
-| `model/diffable.rb` | `as_update` / `dirty?` — delegates to `DiffService` |
-| `model/as_input.rb` | `as_input` (instance) and `as_input(hash)` (class method) — converts diff to GraphQL mutation variables |
-| `model/diffable/diff_service.rb` | Main diff engine: flat classic diff + cascaded reduce through nested `GraphQL::Model` objects |
-| `model/diffable/classic_diff_service.rb` | Low-level change-data extraction (compares `curr_doc` vs `prev_doc`) |
-| `model/diffable/hash_diff.rb` | Hash equality / change detection helpers |
-| `model/diffable/hash_diff_nesting.rb` | Nested key path helpers (`dig_set!`, `dig_delete!`, `dig_path?`) |
-
-## Conventions
-
-- `Client` is graphlient-based and used for schema introspection; `HttpClient` is the actual request sender used in production (set as `client.http_client`).
-- `HashHelpers` is used as both a module mixin (include) and directly via `HashHelpers.keys_to_sym_deep(...)`.
-- `DiffService` handles the `flat:` flag: `flat: true` does a single-level diff; `flat: false` (default) cascades through nested `GraphQL::Model` objects.
-- Root-class objects (`root!` declared) are excluded from cascaded diffs — they represent independent server entities.
-- `AsInput#as_input(target_class:)` delegates to `Input::X.from_model(self)` when a target class is given.
-
-## Related
-
-- `../graphql/logic/base_model.rb` — adds `SnakeCamelAccess` on top of `Common::GraphQL::Model`
-- `../graphql/logic/input.rb` — `Logic::Input` base class built on top of `Model`
-- `../graphql/logic/base_query.rb` — consumes `HttpClient#execute` and `HashHelpers`

data/lib/ecoportal/api/common/graphql/model/CLAUDE.md

@@ -1,28 +0,0 @@
-# common/graphql/model
-
-Concerns that add dirty-tracking diff (`Diffable`) and mutation-input serialisation (`AsInput`) to the base `Common::GraphQL::Model`.
-
-## Contents
-
-| File / class | Purpose |
-|---|---|
-| `diffable.rb` / `Model::Diffable` | Provides `as_update` (returns changed-field hash or nil) and `dirty?`; delegates to `DIFF_CLASS` (defaults to `DiffService`) |
-| `as_input.rb` / `Model::AsInput` | Instance `as_input` (wraps diff as mutation variables) + class-level `as_input(hash)` (key-sym + nil-id cleanup) |
-| `diffable/diff_service.rb` / `DiffService` | Primary diff engine: flat classic diff then cascaded reduce over nested `GraphQL::Model` children |
-| `diffable/classic_diff_service.rb` / `ClassicDiffService` | Low-level diff: compares `curr_doc` vs `prev_doc`, returns `{ id:, changed_field: new_value }` or nil |
-| `diffable/hash_diff.rb` / `HashDiff` | Primitive equality helpers used by `ClassicDiffService` |
-| `diffable/hash_diff_nesting.rb` / `HashDiffNesting` | Nested path helpers: `dig_set!`, `dig_delete!`, `dig_path?` used when building cascaded diff results |
-
-## Conventions
-
-- `DIFF_CLASS = DiffService` is a constant on `Diffable` — subclasses can override it to swap diff strategies.
-- `DiffService` `flat: true` produces a single-level diff (current model only); `flat: false` (default) recurses via `cascaded_reduce` through nested `GraphQL::Model` objects.
-- Objects declared with `root!` in their class are skipped during cascaded diff — they are independent server entities (look-ups only).
-- `as_input` on a model calls `as_update` first; returns `nil` when nothing has changed so callers can skip the mutation.
-- `as_input(target_class:)` is the preferred path when a corresponding `Input::X` class exists — delegates to `target_class.from_model(self)`.
-
-## Related
-
-- `../hash_helpers.rb` — `HashHelpers` used inside `DiffService` for key transforms
-- `../../graphql/logic/input.rb` — `Logic::Input.from_model` is the canonical consumer of `as_update`
-- `../../graphql/logic/base_model.rb` — all concrete models inherit this chain

data/lib/ecoportal/api/graphql/CLAUDE.md

@@ -1,37 +0,0 @@
-# graphql (gem root)
-
-The entry point for the gem: `Ecoportal::API::GraphQL` is the top-level class consumers instantiate; it holds the `client`, wires the `HttpClient`, and exposes builder/compat entry points.
-
-## Contents
-
-| File / class | Purpose |
-|---|---|
-| `graphql.rb` / `GraphQL` | Main entry class — `initialize` builds `Client` + `HttpClient`, exposes `pages`, `registers`, `page`, `action`, `contractorEntity`, `locationStructure`, `currentOrganization` |
-| `graphql_version.rb` | Gem `VERSION` constant |
-| `base/` | Data-only model base classes (no resolvers, no `client`); see `base/CLAUDE.md` |
-| `builder/` | Facade builders that group related mutations under one object |
-| `compat/` | v2-compatible API layer for eco-helpers scripts |
-| `concerns/` | Shared Ruby mixins (`PageCompat`, `DataFieldAccess`, `SnakeCamelAccess`, `FragmentDefinitions`) |
-| `connection/` | `Logic::Connection` subclasses — typed pagination wrappers per entity |
-| `error/` | Domain error classes (`ValidationErrors`, `LocationsError`, `LocationsValidationError`) |
-| `fragment/` | GraphQL fragment heredoc strings + `Fragment.assemble(*syms)` |
-| `helpers/` | Utility modules (`LocationsTree`) |
-| `input/` | Mutation input serialisers; `SearchConf` is a chainable value object |
-| `interface/` | Abstract base models shared by `Base::` and `Model::` (e.g. `BasePage`, `LocationStructure`) |
-| `logic/` | Abstract base classes for queries, mutations, connections — no domain code |
-| `model/` | Concrete domain models with `class_resolver` wiring; subclass their `Base::` counterparts |
-| `mutation/` | Concrete mutation execution classes |
-| `payload/` | Mutation response payload wrappers |
-| `query/` | Concrete query execution classes |
-
-## Conventions
-
-- Load order in `graphql.rb` matters: `logic/base_model` → `error` → `interface` → `base` → `model` → rest.
-- `#pages` returns `Compat::Pages` (v2-compatible); `#page` returns `Builder::Page` (raw mutation facade).
-- `#currentOrganization` returns `Model::Organization` class (not instance) with `client` set — query methods are class-level.
-- `GraphQL` (not `GraphQL`) is the namespace: use `Ecoportal::API::Graphql` alias only for legacy references; internal code uses `GraphQL`.
-
-## Related
-
-- `../../common/graphql/` — HTTP client, auth, and base model infrastructure
-- Downstream: `eco-helpers` calls `.pages` and `.registers` exclusively via `Compat::*`