App, identity and observability

# any object by id, through a shared interface
{ node(id: "P1") { __typename id ... on Party { displayName } ... on Participant { memberNumber } } }
{ nodes(ids: ["PR1", "PL1", "C1"]) { __typename id } }

# one search, three result types, each inside what the caller may read
{ search(term: "sun") { __typename ... on Party { id displayName } ... on Claim { id status amount } } }

# filtered and ordered keyset pagination: pass pageInfo.endCursor as after:
{ claims(first: 2, filter: { status: SUBMITTED }, orderBy: { field: AMOUNT, direction: DESC }) {
    totalCount edges { node { id amount submittedAt } } pageInfo { hasNextPage endCursor } } }

# an idempotent retry (as riley.provider): run it twice, get the same claim id
mutation { submitClaim(input: { planId: "PL1", category: DAILY_LIVING, amount: "12.00",
    serviceDate: "2026-04-20", idempotencyKey: "try-1" }) {
  __typename ... on Claim { id } ... on UserError { message path } } }

interface Node { id: ID! }
interface Party { id: ID!  displayName: String! }
interface UserError { message: String!  path: [String!] }

enum PlanManagement { AGENCY PLAN_MANAGED SELF }
enum SupportCategory { DAILY_LIVING THERAPY EQUIPMENT }
enum SupportRequestStatus { SUBMITTED APPROVED REJECTED }
enum OrderDirection { ASC DESC }
enum ClaimOrderField { SUBMITTED_AT AMOUNT }

type Participant implements Node & Party {
  id: ID!
  displayName: String!
  memberNumber: String!
  schemeNumber: String! @deprecated(reason: "Use memberNumber; removal after 2026-12-31")
  dateOfBirth: Date            # null unless the caller may see it
  plans: [Plan!]!
}
type Provider implements Node & Party { id: ID!  displayName: String!  bookings: [ServiceBooking!]! }
type ServiceBooking implements Node {
  id: ID!  plan: Plan!  provider: Provider!  category: SupportCategory!  reserved: Money!  remaining: Money!
}
type SupportRequest implements Node {
  id: ID!  plan: Plan!  category: SupportCategory!  description: String!
  estimatedAmount: Money!  preferredProvider: Provider
  status: SupportRequestStatus!  decisionReason: String
  booking: ServiceBooking      # set when approved
}

union SearchResult = Participant | Provider | Claim

input ClaimFilter {           # submittedAfter is inclusive, submittedBefore exclusive (RFC 3339)
  status: ClaimStatus  category: SupportCategory  providerId: ID  submittedAfter: String  submittedBefore: String
}
input ClaimOrder { field: ClaimOrderField! = SUBMITTED_AT  direction: OrderDirection! = ASC }
input SubmitSupportRequestInput {
  planId: ID!  category: SupportCategory!  description: String!  estimatedAmount: Money!  preferredProviderId: ID
}
input DecideSupportRequestInput { id: ID!  approve: Boolean!  reason: String!  providerId: ID }
input SubmitClaimInput {
  bookingId: ID!  amount: Money!  serviceDate: Date!
  idempotencyKey: String       # optional; same key + same input → the same Claim, never a second payment
}

type ValidationError implements UserError { field: String!  message: String!  path: [String!] }
type BudgetExceededError implements UserError { message: String!  path: [String!]  remaining: Money!  requested: Money! }
type SelfApprovalNotAllowedError implements UserError { message: String!  path: [String!] }
type IdempotencyKeyReusedError implements UserError { message: String!  path: [String!] }

union SubmitSupportRequestPayload = SupportRequest | ValidationError | BudgetExceededError
union DecideSupportRequestPayload = SupportRequest | SelfApprovalNotAllowedError | ValidationError
union SubmitClaimPayload = Claim | ValidationError | BudgetExceededError | IdempotencyKeyReusedError

type Query {
  node(id: ID!): Node
  nodes(ids: [ID!]!): [Node]!
  search(term: String!, first: Int = 10): [SearchResult!]!
  claims(filter: ClaimFilter, orderBy: ClaimOrder, first: Int = 20, after: String): ClaimConnection!
}
type Mutation {
  submitSupportRequest(input: SubmitSupportRequestInput!): SubmitSupportRequestPayload! @auth(requires: [PARTICIPANT, NOMINEE])
  decideSupportRequest(input: DecideSupportRequestInput!): DecideSupportRequestPayload! @auth(requires: [AGENCY_STAFF])
  submitClaim(input: SubmitClaimInput!): SubmitClaimPayload! @auth(requires: [PROVIDER])
}
type Subscription {
  supportRequestStatusChanged(planId: ID!): SupportRequest!
  claimStatusChanged(planId: ID!): Claim!
}

Plan, Claim and the connection types also implement Node; existing types are unchanged apart from the renames. The self-approval check is a domain rule (see the code page); the @auth directive only gates the role.

realm: demo
enabled: true
bruteForceProtected: true
failureFactor: 10
groups:
  - name: argocd-admins
  - name: argocd-readonly
  - name: grafana-admins
  - name: grafana-viewers
roles:
  realm:
    - name: participant
    - name: nominee
    - name: provider
    - name: agency_staff
users:
  - username: zhaolin.sun
    enabled: true
    realmRoles: [participant]
    groups: [/argocd-admins, /grafana-admins]
    attributes: { participant_id: [P1] }
    credentials:
      - { type: password, temporary: false, value: "$(env:PW_ZHAOLIN_SUN)" } # Secrets Manager demo/keycloak/users
  - username: case.officer
    enabled: true
    realmRoles: [agency_staff]
  - username: demo.guest
    enabled: true
    realmRoles: [participant]
    groups: [/argocd-readonly, /grafana-viewers]
    attributes: { participant_id: [P3] }
clients:
  - clientId: argocd
    publicClient: false
    redirectUris: ["https://argocd.frankbluemind.com/auth/callback"]
    defaultClientScopes: [profile, email, groups]

# argocd-cm
url: https://argocd.frankbluemind.com
admin.enabled: "false"                          # after SSO is verified
oidc.config: |
  name: Keycloak
  issuer: https://auth.frankbluemind.com/realms/demo
  clientID: argocd
  clientSecret: $oidc.keycloak.clientSecret     # key in argocd-secret, written by ESO
  requestedScopes: ["openid", "profile", "email", "groups"]
# argocd-rbac-cm
policy.default: ""                              # no access unless a group grants it
policy.csv: |
  g, argocd-admins, role:admin
  g, argocd-readonly, role:readonly

# grafana.ini (Helm values)
[server]
root_url = https://grafana.frankbluemind.com
[auth]
disable_login_form = true
[auth.generic_oauth]
enabled = true
name = Keycloak
client_id = grafana
client_secret = $__file{/etc/secrets/grafana-oidc/client_secret}
scopes = openid profile email groups
auth_url = https://auth.frankbluemind.com/realms/demo/protocol/openid-connect/auth
token_url = https://auth.frankbluemind.com/realms/demo/protocol/openid-connect/token
api_url = https://auth.frankbluemind.com/realms/demo/protocol/openid-connect/userinfo
role_attribute_path = contains(groups[*], 'grafana-admins') && 'Admin' || contains(groups[*], 'grafana-viewers') && 'Viewer'
role_attribute_strict = true                    # no matching group → no access

// cmd/api/main.go: config comes from OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME,
// OTEL_TRACES_SAMPLER_ARG; an empty endpoint keeps every provider a no-op.
shutdown, err := kitotel.Setup(context.WithoutCancel(ctx), cfg.Telemetry)
if err != nil {
	return fmt.Errorf("telemetry: %w", err)
}
defer kitotel.Flush(log, shutdown, 5*time.Second) // after the drain, inside the grace period

verifier := oidc.New(authn.Config{ /* … */ Transport: kitotel.Transport(nil)})
gql := graphql.NewHandler(svc, graphql.Options{ /* … */
	Telemetry: otelgql.New(otelgql.Options{ClientErrorCodes: []string{graphql.CodeDepthLimit}}),
})

// cmd/api/store.go: the adapter only sees pgx's QueryTracer interface.
pool, err := postgres.Open(ctx, cfg.DatabaseURL, postgres.PoolOptions{ /* … */ Tracer: otelpgx.NewTracer()})
err = otelpgx.RecordPoolStats(pool)

// cmd/api/router.go: the chain's tracing slot.
r.Use(httpmw.Recover(log), httpmw.RequestID, kitotel.HTTPMiddleware("demo-api"), httpmw.AccessLog(log, clientIP) /* … */)

extensions:
  sigv4auth: { region: ap-southeast-2, service: aps }
receivers:
  otlp:
    protocols:
      grpc: { endpoint: 0.0.0.0:4317 }
processors:
  memory_limiter: { check_interval: 1s, limit_percentage: 75, spike_limit_percentage: 20 }
  batch: {}
exporters:
  awsxray: { region: ap-southeast-2 }
  prometheusremotewrite:
    endpoint: https://aps-workspaces.ap-southeast-2.amazonaws.com/workspaces/<workspace-id>/api/v1/remote_write
    auth: { authenticator: sigv4auth }
    resource_to_telemetry_conversion: { enabled: true }
service:
  extensions: [sigv4auth]
  pipelines:
    traces:  { receivers: [otlp], processors: [memory_limiter, batch], exporters: [awsxray] }
    metrics: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [prometheusremotewrite] }