Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

7.1 KB
Raw Blame

complete_graph — schema conventions

What it is

Part of the web client's shared infrastructure: this crate composes the domain GraphQL adapter crates (graphql_soup, graphql_properties, graphql_notification, graphql_email, graphql_entity_mutation, graphql_work_feed, graphql_notification_inbox, graphql_registered_work, with shared plumbing in graphql_common) into the complete GraphQL schema consumed by the client's normalized cache (crates/client, design doc: apps/web/docs/graphql-normalized-cache-plan.md). The conventions below are load-bearing for cache correctness and API consistency. The cache's build validates shapes but cannot validate semantics — that's what schema review is for.

1. id is a reserved, semantic field name (presence-of-id convention)

Clients key cache records by __typename:id. Consequences:

  • An output object type with an id: ID! field is a normalized entity. Two responses containing the same __typename:id pair are merged into one record — so id must identify the same logical value everywhere it can appear, across all queries, arguments, and parent objects.
  • Only name a field id when it is the object's global identity. If a type carries a reference to something else's id, name it accordingly:
    • GraphqlProperty.id is the globally unique entity-property assignment id. propertyDefinitionId remains separate because definitions are shared while assignment values are per-entity.
    • GraphqlSoupChannelMessage.id (renamed from messageId) — it is the message's identity, so it uses the reserved name.
  • Types without an id field are embedded inline in their parent record (SoupPage, participants, property values, DocumentSubType). This is correct for value objects and query-scoped wrappers. Do not add constant or synthetic ids to such types — a constant id (e.g. "soup_page") would merge every instance into a single record globally. A type without an id may only carry fields that are facts about the edge it represents, never facts about an entity — entity facts belong on the entity record where every view shares them. Soup pages therefore return entities directly (there is no per-item wrapper type), and per-view state is limited to list membership and order. A value derived per view (the Soup email thread's sortTs, which depends on the query's emailView) is not an entity fact either: clients must not select it into the shared record, because the last view to fetch the thread would win. Expose the facts it derives from (latestInboundMessageTs, reminderReturnedAt, latestOutboundMessageTs, latestNonSpamMessageTs) and let each view recompute its key.
  • id fields must be exactly ID! (non-null, non-list); the cache build (crates/client/cache-core/build.rs) fails otherwise, and fails if the query root exposes an id.

Review checklist when adding/changing a type:

  1. Does it have a stable global identity? → expose it as id: ID!.
  2. Is its content dependent on where it appears (parent entity, arguments)? → no id field; expose reference ids under descriptive names.
  3. Renaming/removing an id field changes client caching semantics — it rotates cache keys and turns entities into embedded values (or vice versa). Deliberate, but call it out in review.

2. QueryRoot → user (viewer pattern) is the identity witness

All user-scoped data hangs off user: GraphqlUser!, and GraphqlUser.id must be the authenticated user's id from the request context. The client extracts it from every response and passes it to the cache as a session tag: a response for a different user than the one bound to the cache triggers a full wipe-and-rebind (cross-user leak protection on account switches).

  • Never resolve GraphqlUser.id from anything other than the authenticated request context.
  • New user-scoped root data should be added under GraphqlUser, not as new root fields.

3. GraphqlSoupEntity owns the shared entity contract

Every field implemented by all concrete Soup entity types belongs on the GraphqlSoupEntity interface. Today that contract is id, entityType, displayName, metadata, properties, notifications, isFavorited, and viewerPermission.

content is deliberately not part of the interface. Content has different domain shapes and loading policies across documents, email threads, channels, messages, calls, and future entity types. Define it on the concrete entity or a domain-specific composed edge, with the type that domain actually owns.

The interface is the public API contract; Rust crate ownership must not leak into it. Cross-domain resolvers remain composed by SoupEdges in this crate, while graphql_soup's SoupEntityEdges trait declares their associated output types and resolver contract. Adding a field to all concrete entity types therefore also requires adding it to the interface and its SDL contract test. Expensive fields remain lazy because GraphQL only invokes resolvers selected by a query.

4. Soup patches contain hydrated updates or explicit deletions

SoupUpdated.item is non-nullable. Use SoupPatch::hydrate_updated for updated entities and SoupPatch::deleted for explicit deletions. The subscription adapter coalesces realtime patches by entity type and ID (last operation wins), preserving last-occurrence order. Mutation adapters map their own domain effects directly; they must not depend on realtime patch types. Poll hydration futures concurrently so the DataLoader can batch them. Missing items are logged and omitted, never inferred to be deleted. Hydration service errors remain GraphQL errors. Do not reintroduce lazy nullable item lookup inside the update.

Regenerating the SDL

After schema changes:

cargo run -p complete_graph --bin graphql_schema -- static_assets/schema.graphql   # from repo root

The exported static_assets/schema.graphql feeds both the client codegen (apps/web && bun gen-graphql) and the cache metadata codegen. Additive changes keep persisted client caches; a change that makes stored records unsafe needs a bump of CACHE_SCHEMA_COMPATIBILITY_EPOCH in crates/client/cache-core/src/codec.rs.

Email send admission, cancellation and status are exposed by graphql_email; GraphqlUser.pendingEmailSends lists authorized inbox attempts with cursor pagination. Keep this viewer-scoped listing independent of normalized-cache initialization.

Never remove or narrow anything deployed clients send without a dated deprecation (Remove after YYYY-MM-DD, at least 30 days out). cargo x graphql-schema-compat checks the SDL against origin/main, and CI runs it; see step 8 of the field guide.

Saved-view definitions live under authenticated GraphqlUser; mutations use the authenticated request user and a domain service from request data. Run cargo test -p complete_graph --lib saved_view_contract after changing the saved-view contract.

  • Mail capsule negotiation lives in mail_cache_profile: absent/unknown capabilities receive v2; explicit soup-mail-v5 receives current capsules. Never infer client support from the server version.