Backend Service

wspace-headshotmarketing-svc is the GraphQL microservice that powers HeadshotMarketing. It runs on the Burdenoff Workspaces platform, exposes a federated GraphQL schema via the workspace public gateway, and persists data in Postgres 18 + AGE via Prisma 7.x.

Stack

Layer	Technology
Runtime	Bun 1.3.10+
Language	TypeScript 5.9+
Framework	ElysiaJS + GraphQL Yoga
Federation	Apollo Federation v2
ORM	Prisma 7.x
Database	Postgres 18 + AGE (graph extension)
Cache / Events	Azure Managed Redis (Redis Streams via @burdenoff/be-sdk)
Observability	OpenTelemetry + Prometheus
Schema registry	GraphQL Hive Cloud

Repositories

Repo	Path	What
Service	~/products/wspace/headshotmarketing/wspace-headshotmarketing-svc	GraphQL Yoga server, resolvers, modules
State / DB	~/products/wspace/headshotmarketing/wspace-headshotmarketing-state	Docker Compose for local Postgres + Redis

Development

cd ~/products/wspace/headshotmarketing/wspace-headshotmarketing-svc

# Start the state layer (Postgres + Redis)
bun run switch:local

# Install, generate, and run
bun install
bun run gendb
bun run codegen
bun run dev

The service starts on the port configured in its environment (default: host mode, or the ACA-assigned port in containers).

Key scripts

Script	What
bun run dev	Watch mode with codegen + migrate + gendb
bun run build	Compile to dist/ with Bun target
bun run codegen	Generate GraphQL types from schema
bun run gendb	Generate Prisma client
bun run migrate:deploy	Deploy Prisma migrations
bun run test	Vitest unit tests
bun run test:coverage	Coverage report (target ≥80%)
bun run sanity	format:check + codegen + gendb + migrate:deploy + lint + type-check + build + coverage + knip
bun run hive:publish	Publish subgraph schema to Hive Cloud (development)
bun run hive:publish:staging	Publish to Hive Cloud staging
bun run hive:publish:production	Publish to Hive Cloud production

Architecture

The service follows the Burdenoff microservice pattern:

• GraphQL Modules — schema and resolvers are organized into domain modules (campaigns, contacts, deals, pipelines, social, ads, etc.).
• RBAC at the gateway — the workspace public gateway enforces @rbac directives; the service receives identity via x-actor-id, x-actor-type, and x-workspace-id headers.
• Event-driven — emits and consumes events via Redis Streams through @burdenoff/be-sdk.
• Multi-tenant — every row is scoped to a workspace; queries are automatically filtered by workspaceId.

Environment

Local development uses .env and .env.local files generated from the dev Key Vault. The service reads:

Variable	Purpose
DATABASE_URL	Postgres connection (PgBouncer :6432 in alpha/prod)
REDIS_URL	Azure Managed Redis (TLS:10000)
HIVE_TOKEN	GraphQL Hive Cloud publish token
HIVE_REGISTRY	Hive Cloud registry endpoint

Integration

Other services and tools integrate with HeadshotMarketing through the workspace public gateway, not directly to the service:

• App shell (headshotmarketing-app) — via Apollo Client 4 to the workspace gateway.
• CLI (headshotmarketing-cli) — via graphql-request to the workspace + global gateways.
• SDKs (headshotmarketing-sdk-node, headshotmarketing-sdk-python) — via graphql-request / httpx to the same gateways.
• Browser extension — via a custom GraphQL client with dual-token headers.
• VS Code extension — via graphql-request with workspace-scoped tokens.
• MCP server — via graphql-request in @burdenoff/mcp-libs.

Testing

• Unit tests — Vitest in the service repo (target ≥80% coverage).
• Backend E2E — headshotmarketing-doctor exercises the GraphQL API end-to-end through the gateway.

---

• Doctor (E2E)
• Environment Selection