Skip to content

DIRAC FED Developer Guide

This repo implements FED as a GraphQL-first contract and discovery layer for DIRAC. It is the home for DTO/BFF/MCP contracts, domain semantics, and provider adapters.

The governing intent is to bring underlying DIRAC functionality and DTO layers into stable modular BFF contracts that frontend applications can depend on without coupling themselves to backend implementation details that may change.

The marketing domain is one active worked example in the current repo. It is not the full intended scope of FED. The same contract discipline is expected to extend to other DIRAC capability areas, including dashboards and the PA.

Stack Choices

  • Runtime: Node.js + TypeScript.
  • API Style: GraphQL (SDL-first).
  • Discovery: MCP-friendly metadata from SDL descriptions and minimal directives.
  • Messaging: Message-first integration in DIRAC; GraphQL is for heavy/continuous data access and pagination.

Core Responsibilities

  • Define stable domain contracts (DTOs) that are provider-agnostic.
  • Host domain vocabularies for semantic meaning.
  • Provide discovery metadata for tools/agents.
  • Map provider data (Odoo) into DTOs without leaking provider IDs.
  • Enforce auth and entitlements; return structured denial metadata.
  • Keep contract targets stable so implementation can evolve without moving frontend goal posts.

Odoo-Edge ↔ FED Responsibilities (Agreed Compromise)

Odoo-Edge (inside Odoo) - System of record for relational data. - Implements pagination at the source (limit/offset or cursor), especially for large datasets. - Exposes thin REST endpoints or focused controller APIs (e.g., batch-by-ids, filtered lists). - May include light model extensions needed for product data persistence.

FED Core (external, Node/TS) - Owns GraphQL contracts, DTOs, and MCP discovery metadata. - Resolves fields by calling Odoo-Edge and other sources (SSO, telemetry, etc.). - Handles composition, enrichment, and domain-level normalization. - Provides consistent auth/entitlement enforcement and policy-aware denials.

Interaction Style - Default: message-based emit/echo for inter-system workflows. - API exception: use DTO/BFF GraphQL for heavy/continuous access (pagination, large lists). - Keep it pragmatic: do not add rigid layers that slow delivery.

GraphQL Sophistication with Odoo-Edge

  • FED remains the GraphQL layer; Odoo-Edge does not need full GraphQL.
  • FED uses resolvers + batching (DataLoader) to avoid N+1 REST calls.
  • Odoo-Edge should expose endpoints that make GraphQL efficient (batch-by-ids, filters).
  • Implementing GraphQL inside Odoo is possible, but not preferred due to stack divergence.

Repo Structure (Operational)

  • schema/: GraphQL SDL contracts and directives.
  • vocab/: Domain vocabulary files (*.vocab.yaml).
  • resolvers/: Thin orchestration; no heavy logic.
  • services/: Domain composition and rules.
  • providers/: Provider adapters (Odoo clients, queries).
  • mappers/: Provider -> DTO normalization.
  • tests/contract/: Schema, invariants, semantics tests.
  • docs/: Architecture notes and mapping plans.

GraphQL Contract Rules

  • Every type/field/enum has a description.
  • Use minimal directives:
  • @unit("W") for numeric units.
  • @sensitivity(PUBLIC|INTERNAL|RESTRICTED) for classification.
  • @semantics(ref: "domain.key") for semantic meaning.
  • Prefer additive changes; deprecate before breaking.
  • Contract creation must follow the intent-first workflow in Intent-Driven BFF Contracts.
  • Marketing-domain contract design must also follow Modular BFF Design: Marketing Example as the current worked example of modular BFF policy.
  • Live BFF verification is required before downstream scaffolding or sync tooling adopts a contract assumption.

DTO Guidelines

  • Do not expose provider IDs in DTOs.
  • Use domain vocabulary (e.g., publishState, series, category).
  • Keep DTOs workflow-independent and read-optimized.

Odoo as System of Record

  • Odoo is the SPOT for product data.
  • Provider mappings must document the Odoo model sources and any extensions.
  • Shopify references are allowed only as baseline comparisons, not source of truth.

Access Control

  • FED enforces auth/entitlement and sensitivity rules.
  • UXI may apply UX gating but never provides security.
  • Denials should include a policy code and a human-readable reason.

Caching Guidance

  • FED returns cache-friendly DTOs and headers when possible.
  • UXI and CDN handle ISR/edge caching.

Initial Deliverables (Product Marketing v1)

  • schema/marketing.graphql (SDL contract).
  • vocab/marketing.vocab.yaml (semantic registry).
  • docs/odoo-mapping.md (model mapping + persistence plan).
  • tests/contract/marketing.test.ts (contract invariants).

Modular BFF Direction

  • dirac-fed is intended to host multiple modular BFF contracts over shared DIRAC capability domains when that is the clearest way to serve UXI needs.
  • Current documented target modules are Contact BFF, Product BFF, Article BFF, Page BFF, and Site BFF as the active marketing-domain example.
  • Future FED domains may include other UXI capability areas such as dashboards and the PA.
  • Do not collapse these modules into one mixed contract unless that contract is intentionally designed and verified as such.