api-contracts

Summary: The contract-first source of truth for all new 7Mind and 7Sleep HTTP APIs, authored in TypeSpec and published as OpenAPI 3 specifications and Redoc HTML on GitHub Pages. Sources: direct code inspection (main.tsp, tspconfig.yaml, package.json, Justfile, contracts/, .github/workflows/, docker/) Last updated: 2026-05-15

---

Purpose

The repo encodes the agreed shape of HTTP APIs flowing between elixir-backend and its clients (7mind-mobile-apps-monorepo, nuxt-website, partner integrations). It is explicitly described in the README as a contract “owned by everyone, not just the Backend Squad” so mobile and backend engineers can review API design in one place. Contracts may drift slightly from production — they can be ahead or incomplete — and PRs to reconcile drift are encouraged.

Four distinct services are modelled side by side, each with its own staging and production host:

Service namespace	TypeSpec file	Production host	Staging host
SevenMind	contracts/7mind.tsp	https://magic.7mind.de	https://magic.6mind.de
SevenSleep	contracts/7sleep.tsp	https://magic.7sleep.de	https://magic.6sleep.de
Identity	contracts/identity.tsp	https://id.7mind.de	https://id.6mind.de
Internal	contracts/internal.tsp	https://magic.7mind.de	https://magic.6mind.de

Stack

• TypeSpec (Microsoft) as the modelling language: @typespec/compiler, @typespec/http, @typespec/openapi3, @typespec/rest (all pinned to latest in package.json)
• Node 20.12.2 (via asdf, .tool-versions)
• @redocly/cli to render OpenAPI YAML into HTML documentation
• Imposter (outofcoffee/imposter-all) as the local mock API server
• Docker Compose for local docs preview and mock API
• just as the task runner (Justfile)
• A small JS decorator (contracts/shared/decorators.js) that re-exports $summary as $templatedSummary because the templated form is not exported publicly by TypeSpec

Key Files / Entry Points

• main.tsp — root file, imports the four service contracts
• tspconfig.yaml — emits OpenAPI 3 as YAML, file name template specs.{service-name}.{version}.yaml
• contracts/7mind.tsp, contracts/7sleep.tsp, contracts/identity.tsp, contracts/internal.tsp — per-service @service + @server declarations and namespace imports
• contracts/<service>/<bounded-context>.tsp — one file per bounded context within a service (e.g. 7mind/user.tsp, 7mind/monetization.tsp, 7mind/practice.tsp)
• contracts/shared/common.tsp — common request/response models, error types, auth schemes, locale and versioning header aliases
• contracts/shared/prevention_models.tsp — ZPP / prevention-specific shared models
• contracts/shared/search.tsp — Algolia search config model
• Justfile — just serve (default), just compile, just html, just format[-check], just docker
• package.json scripts — compile, format[-check], generate-html, dev:7mind, dev:7sleep
• docker/docs/compose.yaml — Redoc containers on ports 4080-4083
• docker/mock-api/compose.yaml — Imposter containers on ports 5080-5083
• publish/_templates/*.html.hbs — Handlebars templates wrapping the Redoc output for each service
• .github/actions/setup and .github/actions/build-html — shared composite actions for CI
• CODEOWNERS — per-bounded-context ownership (see Conventions)

Deployment

Production: GitHub Pages at https://sevenmind.github.io/api-contracts/. Triggered by every push to main via .github/workflows/publish-main.yml, which delegates to reusable-publish.yml. The workflow compiles TypeSpec to OpenAPI YAML, renders Redoc HTML for all four services, downloads any open PR preview artifacts, and deploys the resulting static site through actions/deploy-pages@v4. Pages deploys are serialised by a concurrency group named pages; in-progress runs are not cancelled.

PR previews: .github/workflows/publish-pr-preview.yml runs on opened and synchronize events when main.tsp, contracts/**, publish/**, package.json, package-lock.json, or the workflow file itself change. It builds the HTML, uploads it as the artifact pr_<number> with 30-day retention, re-runs reusable-publish.yml, and posts (or updates) a “PR Preview” comment linking to …/preview/pr_<number>.

CI checks: .github/workflows/check.yml runs npm run format-check and npm run compile on every push as a matrix job.

Changelog: .github/workflows/post-to-changelog.yml posts to the #backend-squad-changelog Slack channel via secrets.CHANGELOG_URL when a merged PR carries the changelog label. Uses actions/cache keyed by PR number to guarantee only one post per PR.

Local docs / mock API: just serve starts both Redoc (localhost:4080-4083) and the Imposter mock API (localhost:5080-5083) via Docker Compose and re-compiles on .tsp changes if entr is installed.

Dependencies

External services: none at runtime. Build-time dependencies are the public npm registry for TypeSpec/Redoc and Docker Hub for outofcoffee/imposter-all and redocly/redoc. Publication relies on GitHub Pages and GitHub Actions.

Internal: this repo has no Elixir/Dart/TS code consumers wired into its CI — it produces human-readable documentation, not generated client code. Consumers today are humans reading the published site; agents in elixir-backend, 7mind-mobile-apps-monorepo, and nuxt-website should treat the published spec as a coordination artefact, not as a typed dependency. If automated code generation is added later it should be documented here.

Integration Points

• elixir-backend implements the contracts on the server side. Many endpoints carry #deprecated "Use Backend.UserIdentity instead" or similar pragmas, signalling the live backend migration from legacy /user_identity and /auth (SuperTokens) routes to the new /user routes.
• 7mind-mobile-apps-monorepo and nuxt-website consume the contracts on the client side. They are expected to honour the auth schemes and versioning headers defined in contracts/shared/common.tsp.
• Slack #backend-squad-changelog receives merged-PR notifications when the changelog label is set.
• GitHub Pages hosts the rendered docs site.

Conventions

Bounded contexts as files: each service folder (contracts/<service>/) contains one .tsp per bounded context (access, activation, analytics, content, monetization, practice, prevention, user). Larger contexts use a subfolder of the same name (e.g. 7mind/practice/history.tsp, 7mind/content/favourites.tsp). When adding a new contract, follow this layout and import the new file from the service-level .tsp.

Code ownership by squad (CODEOWNERS):

• contracts/*/activation.tsp and activation/ — @sevenmind/activation
• contracts/*/content.tsp and content/ — @sevenmind/content
• contracts/*/practice.tsp and practice/ — @sevenmind/retention
• contracts/*/monetization.tsp and monetization/ — @sevenmind/monetization

Datetime convention: all date-times default to UTC ISO 8601. This decision is repeated in the README and at the top of every service file. Use utcDateTime in models unless explicitly justified otherwise.

API versioning: see api-versioning-headers. Clients use the user-agent header to declare app name, version, and build, and may optionally request a specific response version via the accept header.

Auth schemes: three reusable models are defined in contracts/shared/common.tsp and applied via @useAuth:

• Shared.Common.Requests.SuperTokensAuth — bearer st-access-token (used on deprecated /auth/* routes, see supertokens-auth)
• Shared.Common.Requests.APIv1Auth — bearer legacy auth_token from the v1 API (used on Mondia link and Chargebee self-serve portal)
• Shared.Common.Requests.BackendSessionAuth — cookie backend_session (used on the new /user/* and other authenticated routes)

Mondia and Fastspring webhooks: the contracts include mondia_webhook and Fastspring HMAC-signed webhook endpoints under SevenMind.Monetization. Mondia uses HTTP Basic auth (with a lowercase “basic” scheme prefix that violates RFC but is accepted in practice). See chargebee-billing for the broader monetization picture.

Deprecation policy: TypeSpec #deprecated pragmas are used liberally to flag migration paths. New contracts should be added under the non-deprecated paths (/user rather than /user_identity, Backend.UserIdentity rather than direct SuperTokens proxying).

Format check is enforced: tsp format --check **/**/*.tsp runs in CI. Run npm run format (or just format) before pushing.

Slack changelog: add the changelog label to a PR if it should announce itself in #backend-squad-changelog on merge.

Asset templates: the four Redoc HTML templates live in publish/_templates/; per-service favicons and assets live in publish/<service>/assets/. publish/ is git-ignored but checked-in for template files only.

Agent Change Log

2026-05-15 — stub created, awaiting content seeding from code inspection 2026-05-15 — initial knowledge extraction from codebase