[Sebas1705]

What was wrong versus the code (origin/main, 2026-11-12)

• architecture/key-sequence-flows.md (2026-04-22) described routes that do not exist: GET /v1/games/quiz/random with a "cache miss -> call AI" branch, PATCH /admin/routing/ai-engine, POST /rounds/:id/result, POST /players/:id/events. In code (checked gateway -> BFF -> service):
  • random is GET /v1/mobile/games/quiz/random -> bff-mobile src/app/routes/mobile.ts:373 -> GET /games/models/random (shared-sdk-client game-routes.ts:280), and randomModels only reads stored Prisma rows; there is no AI fallback. POST /v1/mobile/games/*/generate is also served from the inventory (mobile.ts buildGeneratedGameFromInventory).
  • changing the AI target is PUT /v1/backoffice/ai-engine/target -> bff-backoffice backoffice.ts:1848 -> PUT /internal/admin/llama-target on ai-engine; the gateway has its own separate PUT /internal/admin/ai-engine/target.
  • history is GET /v1/backoffice/services/microservice-quiz/data?dataset=history -> GET /games/history.
  • game results go to POST /v1/mobile/games/events and stay in the BFF PlayerStore; bff-mobile only calls GET /users/me/profile on the users service.
  • ingest has no BFF route: POST /games/ingest on the game service -> gateway /internal/ai-engine/ingest/quiz -> ai-engine /ingest/quiz.
• architecture/target-architecture.md and c4-views.md drew Gateway -> AIAPI but not quizz/word-pass -> gateway -> ai-engine, which is what platform-infra/kubernetes/base/microservice-quizz/api-deployment.yaml:43 configures (AI_ENGINE_BASE_URL=http://api-gateway:7005/internal/ai-engine). They also drew Contracts feeding the gateway and BFFs and the SDK feeding only those three.
• c4-views.md:71 and glossary.md:28 said shared-sdk-client is TS/Python/Kotlin generated clients; ADR 0003, contract-governance.md and domain-model.md said the SDK is regenerated from contracts. It is an internal TypeScript library imported by six services; nothing is generated.
• master-alignment.md claimed "event-driven parcial" and events in ai-engine/quizz; service-communication.md said event contracts are versioned. There is no broker, no producer and no consumer of the event schemas.
• quality-attributes.md QA-P1 used the old route and a cache-hit measure that does not apply to a read-only path; QA-M1, QA-E1 and UC-14 assumed SDK regeneration.
• True-false exists only in ai-engine (/generate/true-false, /ingest/true-false); the gateway does not proxy it.

What changed

• key-sequence-flows.md: SF-01, SF-02, SF-04, SF-05, SF-06 rewritten from the real routes; added SF-07 (generation worker and processes) and a true-false note. SF-03 (CI/CD) kept, with a status note: platform-infra deploy.yaml is manual-only on main. Not otherwise re-verified.
• target-architecture.md: "current vs target" banner; quizz/word-pass -> gateway -> ai-engine; SDK edges to all six consumers; Contracts edge reduced to "docs, CI validation only"; async layer and true-false stated honestly.
• c4-views.md, glossary.md, ADR 0003 (status note, text kept), domain-model.md (contracts table now points to the Zod schemas in game-schemas.ts), contract-governance.md, quality-attributes.md, use-cases.md.
• Marked as not implemented / future work (nothing deleted): event schemas, Outbox and event-driven claims in master-alignment.md (banner + cells), service-communication.md, tfm-practice-matrix.md; contract-driven SDK regeneration (target, not current).
• ai-content-generation.md: true-false has no consumer.

Overlap with docs#10

AxiomNode/docs#10 edits architecture/repository-map.md, operations/cicd-workflow-map.md and operations/deployment-strategy.md. This PR touches none of them, so there are no conflicting hunks. Only a content link: the SF-03 status note here is consistent with the staging-decommissioned wording in #10 (I confirmed the manual-only deploy.yaml on platform-infra main independently).

Related

• AxiomNode/contracts-and-schemas#1 (sibling draft PR): OpenAPI additions, generated route inventory for the gateway/BFFs (linked from SF-07 as a path, not a markdown link), event schemas marked not implemented.
• AxiomNode/microservice-users#5 (open, unmerged) proposes POST /users/me/games/events/batch. SF-06 mentions it as unmerged and describes only what is on main; nothing here depends on it.
• shared-sdk-client PR Create icon and logos of app and project #4 (removes the empty python/kotlin/openapi/tooling folders) is not required for these docs; they describe the library as TypeScript-only.

Verification

Done:

• Every route and call in the rewritten flows was read in code on origin/main (gateway 23e067b, bff-mobile a3a3fc5, bff-backoffice eb4a4a7, plus quizz, ai-engine, shared-sdk-client, platform-infra).
• The repository's relative-link check (validate-docs.yml) was ported to Node and run locally: 83 files, no broken links; line endings (CRLF) preserved in every file.

Not verified:

• Mermaid diagrams were not rendered (no renderer available); I checked syntax by eye only.
• SF-03 (CI/CD) beyond the deploy trigger; the "ai cache: Redis" container in c4-views.md (ai-engine supports tinydb or redis backends; I did not check which one is deployed); whether the ai-engine llama target override persists across pod restarts (stated as unverified in SF-02); the mobile app GameType claim comes from the review notes, the app repository was not re-read; exact HTTP status mapping for slow upstreams in SF-04.
• Other docs not listed here may still carry the same stale claims (for example guides that mention shared-sdk-client in passing); I searched for "kotlin/python" SDK mentions, event/Outbox, true-false and the old route names only.
• Spanish text in master-alignment.md was kept where untouched; my additions there are English or Spanish matching the cell.