Skip to main content

​
Ownership model

This repository is the cross-service architecture reference. Each service owner is responsible for updating the relevant page in the same change set whenever they alter:
  • public APIs, gRPC contracts, or event payloads;
  • state ownership, queues, topics, database migrations, or cache keys;
  • external integrations or secrets/configuration requirements;
  • Helm deployment topology, worker processes, scaling, alerts, or runbooks.

​
Update workflow

  1. Change the relevant .mdx page and docs.json only when navigation changes.
  2. Prefer source-path references for internal evidence, for example vector/app/service/payment_service.py.
  3. Mark unsupported relationships as Inference and state the confidence/reason.
  4. Add or update Mermaid diagrams when service edges change.
  5. Run the Mintlify validation/preview command used by your CI or Mintlify integration.
  6. Have both the affected service owner and platform owner review cross-service changes.

​
Documentation quality bar

Every service page should answer:
  1. What business capability does it own?
  2. What are its HTTP/gRPC/worker entry points?
  3. Which data stores and queues does it own or use?
  4. Which services and third parties does it call?
  5. How is it deployed and observed?
  6. What are its idempotency, failure, and rollback considerations?

​
Mintlify connection

The local site is Mintlify-ready through docs.json and MDX navigation. To publish it, create or connect the remote repository in the intended GitHub organization, push this repository, then select the repository in Mintlify. The current GitHub token cannot create repositories, so remote creation/push requires an authorized account or organization token.