7Mind Brain

typespec-contracts

4 min read

Summary: 7Mind authors all new HTTP APIs in TypeSpec inside the api-contracts repo and ships the resulting OpenAPI 3 specs as Redoc HTML on GitHub Pages, treating the published site as a shared coordination artefact rather than as generated client code. Sources: direct code inspection of api-contracts (main.tsp, tspconfig.yaml, package.json, .github/workflows/, docker/) Last updated: 2026-05-15

What is captured

The repo defines four parallel services, each in its own root file under contracts/:

  • SevenMind — the consumer-facing 7Mind API (magic.7mind.de)
  • SevenSleep — the consumer-facing 7Sleep API (magic.7sleep.de)
  • Identity — the identity service (id.7mind.de) plus a SuperTokens sub-namespace covering deprecated direct-to-SuperTokens routes
  • Internal — internal endpoints (admin, healthchecks, Prometheus metrics)

Within each service, bounded contexts live in subfolders matching the modulith-domain-model domains on the server side: access, activation, analytics, content, monetization, practice, prevention, user. Each context owns its own .tsp file (and optional subfolder for large contexts like practice and content).

Shared building blocks live in contracts/shared/:

  • common.tsp — error models (Error<S>, CommonError, PremiumError, etc.), the three auth schemes, locale and versioning header aliases
  • prevention_models.tsp — ZPP / prevention models reused across services
  • search.tsp — Algolia search configuration

Toolchain

.tsp files                   contracts/**/*.tsp
   │
   │  @typespec/openapi3 emitter (tspconfig.yaml)
   ▼
specs.<service>.yaml         tsp-output/@typespec/openapi3/
   │
   ├─ @redocly/cli ──▶ static HTML (publish/<service>/index.html)
   │                       │
   │                       └─ GitHub Pages: sevenmind.github.io/api-contracts/
   │
   └─ outofcoffee/imposter-all ──▶ local mock API (ports 5080-5083)

Build-time dependencies (npm, pinned to latest): @typespec/compiler, @typespec/http, @typespec/openapi3, @typespec/rest, @redocly/cli. Runtime: none.

The OpenAPI YAML is the only emitted artefact today. No client SDKs are auto-generated — mobile and web clients hand-write their wire types and use the published spec as the agreed source of truth. If automated code generation is added later, update both this page and the api-contracts repo note.

How a new endpoint gets added

  1. Pick the right service and bounded context (or create a new .tsp under contracts/<service>/<context>/ and import it from <service>/<context>.tsp).
  2. Add models and an interface with @route, @summary, @doc decorators.
  3. Apply one of the three auth schemes from Shared.Common.Requests via @useAuth.
  4. Run npm run format (or just format) — the format check is enforced in CI.
  5. Open a PR. A “PR Preview” comment will appear linking to …/preview/pr_<number> with the rendered Redoc site.
  6. After merge, push to main triggers the publish workflow and the live docs update.

Publish pipeline

  • .github/workflows/check.yml — format + compile matrix on every push.
  • .github/workflows/publish-pr-preview.yml — builds HTML on PR open/sync, uploads pr_<number> artefact (30-day retention), posts/updates the preview comment.
  • .github/workflows/publish-main.yml — on push to main, calls reusable-publish.yml.
  • .github/workflows/reusable-publish.yml — the production GitHub Pages deploy; downloads open PR preview artefacts so previews remain visible alongside main.
  • .github/workflows/post-to-changelog.yml — posts to the #backend-squad-changelog Slack channel when a merged PR has the changelog label.

What agents in other repos should know

  • The published spec is design-leading, not always production-accurate. It may be ahead of elixir-backend or slightly behind it. When you spot drift, opening a PR against api-contracts is encouraged.
  • Endpoints marked #deprecated in the contracts indicate an in-flight migration (e.g. /user_identity/* is being replaced by /user/*). New clients should target the non-deprecated path.
  • The mock API (localhost:5080-5083 via just serve) is useful for client development without a live backend.
  • Adding or changing a contract is a code-owned activity — see the CODEOWNERS rules in the api-contracts repo note.

Graph View

Backlinks