Account Nexus Docs is the living technical reference. Service owners update it as their APIs, design decisions and implementation evidence change. Historical phase reports are not the main specification.
Where to document a change
| Change type | Canonical editable source |
|---|---|
| Architecture choice, trade-off, owner approval | Platform decision register and the relevant platform topic |
| Cross-service request, identity, data ownership or error semantics | Platform interface map, plus each affected service’s interface page |
| Service behavior, responsibilities or limitations | That service’s overview page |
| NEW implementation/migration progress | Migration status and readiness pages |
| Release acceptance / production status | Readiness page, with dated and verifiable evidence |
Decision lifecycle
- Proposed: record the problem, owning service, candidate behavior, affected contracts and what remains unverified.
- Approved design: record the decision, rationale, alternatives and explicit signoff status. Approval does not imply implementation.
- Implemented: update the owning service’s interface and overview sources; link the affected platform page.
- Verified: record which focused tests or integration gates really ran and what they proved.
- Deployed: record the released artifact, health check and rollback evidence only after actual production verification.
- Superseded: replace outdated guidance and keep only a brief decision reason; don’t accumulate phase-by-phase narratives.
Fast update rule
For a routine change, update one service and at most its immediately affected interface/decision page. Prefer short Markdown summaries with explicit boundary rules over dozens of generated QA reports. Avoid copying old logs or scanning the entire repository. A changed contract should not silently alter another service’s authority.
Security and publication
The site is public and read-only. Publishing design decisions is expected, but never include secrets, private keys, access tokens, customer records, host-private paths, raw operational logs, or an exploitable internal security configuration. Write safe architectural summaries instead.
Rebuild and rollout
Run the docs-only static build. The generated pages are mounted read-only into independently running documentation containers. Editing the Markdown sources does not start or deploy runtime application services. Check the docs endpoints after a change.
Language: English only.