Skip to main content

​
CLAUDE.md

This file guides Claude Code (claude.ai/code) when working in this repository.

​
Project Overview

orqex/orchestrate-docs is the official Orqex documentation, built with Mintlify. It is bilingual (English en/, French fr/) and covers: conceptual guides, a generated API reference, and SDK documentation. It is published at docs.orqex.com once connected in the Mintlify dashboard.

​
Structure

docs.json                    Mintlify config: theme, colors, navigation, languages
api-reference/openapi.json   OpenAPI 3.1 — the API Reference is generated from this
en/ , fr/                    Mirrored content per language
  index.mdx                  Introduction
  quickstart.mdx
  authentication.mdx
  concepts/                  Core concepts (overview, flow, gateways, orchestration,
                             intents, attempts, next-actions, checkout, refunds,
                             webhooks, idempotency, pagination, errors)
  sdk/php/                   PHP SDK guides (future SDKs go under sdk/<lang>/)
images/                      Brand logo and icon, light/dark (orqex-logo-*, orqex-icon-*)

​
Local commands

npx mint dev            # preview at http://localhost:3000
npx mint broken-links   # validate links and config

​
Conventions

  • Theme uses the Orqex brand colours (colors.primary #144419, light #cdf546, dark #144419) and the shared Axazara fonts (Sang Bleu Republic / Euclid Circular B from fonts.axazara.com), aligned with the Chariow docs conventions (docs.json keys: fonts, seo, api, contextual, interaction; package.json with mintlify). Brand logo/icon in images/ are used as-is.
  • Tabs: Guide, API Reference, SDK, Dashboard. The Dashboard tab documents the dashboard at the capability level (derived from the Core API), not screen-by-screen.
  • Bilingual parity: every page exists in both en/ and fr/, and both language navigations in docs.json stay in sync. Prose is translated; code samples stay in English; keep correct French accents.
  • Navigation: to add a page, create the .mdx and list its path (without extension) under the right language + tab in docs.json. Internal links use absolute paths like /en/concepts/....
  • SDK docs live under sdk/<language>/ (currently sdk/php/), so new SDKs slot in cleanly. The Laravel guide is a page under sdk/php/.

​
API reference

  • The API Reference is generated from api-reference/openapi.json. Edit the spec, not per-endpoint pages. Keep it faithful to the Orqex public API (orqex/orchestrate-api, routes/api/public/v1.php); never invent fields, paths, enum values or response shapes.
  • Mintlify only supports internal $ref within a single OpenAPI document.

​
Accuracy rules

  • Mirror the backend. When documenting a concept (gateways, orchestration strategies, webhook events/payloads), verify against orqex/orchestrate-api before writing.
  • Do not fabricate. Orqex outbound webhooks are currently unsigned (doNotSign); the webhooks page says so and recommends re-fetching the payment to verify. Update this when signing ships.
  • Manual capture and the reconciliation report return HTTP 501 today; the spec documents them as not-yet-available.

​
Validation before a PR

  • docs.json must be valid JSON and every referenced page path must resolve to a file.
  • Run npx mint broken-links.
  • main is protected (PR required); never push to it directly.