--- id: SVC-PFM-SEC-customers title: Customers Service Module product_area: platform module: security repository: services-platform source_module: modules/customers revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 owns: - DOM-PFM-SEC-001 does_not_own: - Workspaces and their lifecycle records belong to the Workspaces service. - Security owns memberships, custom definitions and staff access grants. - Licensing and commercial systems own licenses and contracts reached through the commercial reference. operations: - operation_id: health intent: Return API deployment health and build metadata. access: public permission: 'none: the shared health route' realises: [] published_to_submissions: 'not published: deployment metadata only.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:healthRoute - operation_id: createCustomer route: POST /customers intent: Create the chosen customer identifier through the ordinary route and reconcile standing administrator access atomically. access: system permission: hq.customers.create realises: - CAP-PFM-SEC-001 published_to_submissions: 'not published: security or workspace administration, identity handling, or an administrative read; no Submissions operation binding is declared.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:createCustomer - operation_id: listCustomers route: GET /customers intent: Return only the caller’s reachable customer records. access: console permission: platform.customers.read realises: - CAP-PFM-SEC-001 published_to_submissions: 'not published: security or workspace administration, identity handling, or an administrative read; no Submissions operation binding is declared.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:listCustomers - operation_id: getCustomer route: GET /customers/{id} intent: Return the reachable customer, treating an inaccessible record as absent. access: portal permission: platform.customers.read realises: - CAP-PFM-SEC-001 published_to_submissions: 'not published: security or workspace administration, identity handling, or an administrative read; no Submissions operation binding is declared.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:getCustomer - operation_id: updateCustomer route: PUT /customers/{id} intent: Replace editable customer fields with the supplied record version. access: console permission: platform.customers.update realises: - CAP-PFM-SEC-001 published_to_submissions: 'not published: security or workspace administration, identity handling, or an administrative read; no Submissions operation binding is declared.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:updateCustomer - operation_id: patchCustomer route: PATCH /customers/{id} intent: Apply partial customer edits using the version read by the handler. access: console permission: platform.customers.update realises: - CAP-PFM-SEC-001 published_to_submissions: 'not published: security or workspace administration, identity handling, or an administrative read; no Submissions operation binding is declared.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:patchCustomer - operation_id: deleteCustomer route: DELETE /customers/{id} intent: Remove a customer without workspace references and its standing grants in one transaction. access: system permission: hq.customers.delete realises: - CAP-PFM-SEC-001 published_to_submissions: 'not published: security or workspace administration, identity handling, or an administrative read; no Submissions operation binding is declared.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:deleteCustomer - operation_id: createHqCustomer route: POST /hq/customers intent: Create a customer through HQ without the ordinary route’s standing-access reconciliation. access: system permission: hq.customers.create realises: - CAP-PFM-SEC-001 published_to_submissions: 'not published: security or workspace administration, identity handling, or an administrative read; no Submissions operation binding is declared.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:createHqCustomer - operation_id: listHqCustomers route: GET /hq/customers intent: Search and page HQ customer records with computed workspace counts. access: system permission: hq.customers.read realises: - CAP-PFM-SEC-001 published_to_submissions: 'not published: security or workspace administration, identity handling, or an administrative read; no Submissions operation binding is declared.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:listHqCustomers - operation_id: getHqCustomer route: GET /hq/customers/{id} intent: Return HQ customer details and workspace summaries. access: system permission: hq.customers.read realises: - CAP-PFM-SEC-001 published_to_submissions: 'not published: security or workspace administration, identity handling, or an administrative read; no Submissions operation binding is declared.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:getHqCustomer - operation_id: patchHqCustomer route: PATCH /hq/customers/{id} intent: Apply supplied HQ customer fields while retaining omitted values, including the commercial-reference behavior under review. access: system permission: hq.customers.update realises: - CAP-PFM-SEC-001 published_to_submissions: 'not published: security or workspace administration, identity handling, or an administrative read; no Submissions operation binding is declared.' provenance: observed source: services-platform:modules/customers/aws/api/customers.routes.ts:patchHqCustomer events: [] jobs: [] integrations: [] consistency: - rule: Customer persistence validates row writes and rejects mismatched supplied versions. kind: transactional compensation: Database failure rolls back the row write; there is no external-system compensation. - rule: Ordinary customer creation reconciles standing administrator grants transactionally; HQ creation does not invoke that reconciliation. kind: transactional compensation: A later standing-access reconciliation can create missing grants, subject to eligibility and preserved revocations. - rule: Customer deletion removes standing grants atomically and remains blocked by any workspace reference. kind: transactional compensation: A blocked deletion removes neither customer nor standing grants. evidence: - 'services-platform at ad3f6a65: modules/customers/aws/api/customers.routes.ts, customer-api-mapper.ts, customers.schemas.ts; services/persistence/customers.ts; db/customers.table.ts; aws/platform.service.ts (CUSTOMERS_PERMISSIONS, HQ_CUSTOMERS_PERMISSIONS); docs/standards/submission-compatible-operations.md; docs/standards/record-write-contracts/compliance-by-service.md (services-platform).' examined_at: '2026-10-23' examiner: codex controls: [TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Customers Service Module ## What This Service Is For The Customers service owns the commercial organization record and its administrative operations. Workspace, membership and grant ownership remain with their declared services. It exposes no inference calls, jobs or business events. ## Boundary Workspaces and their lifecycle records belong to the Workspaces service. Security owns memberships, custom definitions and staff access grants. Licensing and commercial systems own licenses and contracts reached through the commercial reference. ## Operations in Words Customer administration groups ordinary customer reads/edits with HQ creation, search and maintenance. The direct and HQ creation paths retain their distinct reconciliation behavior. The operation rows retain declaration access and permission values, capability references and publication status. No operation declares a Submissions binding. Missing replacement versions and handler-read patch versions remain findings against the record-write standard. ## Events and Jobs No jobs or domain events are declared by this service. ## Consistency Guarantees Creation has two implementations: the ordinary path reconciles standing grants inside its transaction; HQ creation omits that call. Deletion removes grants with the customer but is protected by workspace references.