docs: establish canonical PRD TRD architecture ADR UML and ERD baseline

[seonghobae]

Why

The repository had strong feature/method documentation (AGENTS.md, CLAUDE.md, rubric/scoring contract docs, method doctoring, release/commercial evidence), but the durable system design remained distributed across feature docs, PR bodies, research discussions, and agent guidance. There was no canonical product/technical/architecture spine that could answer what the system owns, how components relate, which decisions are durable, what is implemented vs planned, or how requirements map to evidence.

Documentation audit finding

Before this change the corpus was strong at feature-level scientific and operational evidence, but insufficient as a canonical architecture package because PRD, TRD, root architecture description, ADR index, coherent UML views, logical ERD, requirements traceability, and a documentation-completeness audit were absent.

Added canonical baseline

• ARCHITECTURE.md — ISO/IEC/IEEE 42010-style system-of-interest, stakeholders, viewpoints, bounded contexts, module/data/deployment architecture and fitness functions.
• docs/PRD.md — requirements for Assessment/Rubric/Scoring contracts, generated-item lifecycle, automated essay and reference-free RAG measurement, model selection, recovery, multilevel/time, reporting, and release evidence.
• docs/TRD.md — enforceable Rust/PyO3/Python, numerical, psychometric, security/privacy, coverage/docstring, packaging and release requirements.
• docs/architecture/UML.md — component, contract-class, item-generation and scoring sequences, model-selection activity, item-bank state machine, multilevel/temporal and deployment views.
• docs/architecture/ERD.md — logical measurement/provenance and multilevel/temporal ERD, explicitly not a physical hosted database schema.
• docs/adr/README.md plus ADR-001..008 — domain boundary, Rust-first numerics, content-addressed provenance, governed item bank, relation-safe model selection, multilevel/time, fallible-rater/LLM boundary, and logical persistence ownership.
• docs/requirements_traceability.md — PRD→TRD/ADR→implementation/evidence maturity map.
• docs/documentation_coverage.md — explicit before/after completeness audit, remaining P0/P1/P2 documentation gaps, and maintenance gate.
• docs/README.md — canonical documentation navigation and authority rules.
• docs/doctoring/architecture_governance_baseline.md — standards/source audit, APA 7 references, CSAP/SOC 2 readiness positioning, and falsification criteria.
• tests/test_architecture_documentation_contract.py — CI-enforced architecture-spine existence, requirement coverage, boundary, UML/ERD, ADR/traceability, and anti-overclaim regression contract.

Conversation/research coverage

The baseline consolidates durable conclusions from the project’s reference-free RAG, dynamic evidence-grounded rubric/item-bank, automated scoring/essay evaluation, correlated-MIRT/bifactor/higher-order/testlet/two-tier/many-facet model selection, formal relation-safe comparison, adaptive rotation, true-parameter recovery, multilevel/multiple-membership, temporal/longitudinal, Rust/GPU, privacy/provenance, MSA, LLM orchestration, and release-governance work.

It deliberately marks roadmap/active-branch capabilities as partial or planned rather than claiming they are on protected main.

Architecture boundary

fast-mlsirm remains the standalone, domain-neutral measurement and psychometric computation layer. Hosted assessment lifecycle, identity/RBAC, tenant/product persistence, HTTP/UI, billing, customer data-rights workflow, and deployment stay downstream (notably Psychometrics Commons or the owning CWL service). The logical ERD documents interoperable contract semantics without adding an ORM/database dependency.

Standards/research baseline

The package is organized around ISO/IEC/IEEE 42010:2022 architecture descriptions, ISO/IEC/IEEE 29148:2018 requirements engineering, ISO/IEC/IEEE 12207:2026 software life-cycle processes, ISO/IEC/IEEE 15289:2019 life-cycle information items, ISO/IEC 25010:2023 product quality, ISO/IEC 5338:2023 AI lifecycle processes where applicable, ISO/IEC 42001:2023 management-system concerns without certification claims, and OMG UML 2.5.1. Scientific claims retain APA 7 references and conservative interpretation boundaries.

Scope and merge boundary

This PR changes documentation architecture plus one documentation-contract test only. It changes no runtime model formula, package dependency, physical DB schema, workflow authority, external service contract, or release version.

Keep Draft until:

• exact-head CI, Security Scan, and SAST applicable to this head are green;
• documentation links, Mermaid syntax, terminology, standards/source claims, and internal consistency are reviewed;
• the documentation-contract regression passes in the repository suite;
• current-head automated/independent review has no valid unresolved architecture finding.

The baseline is intentionally not a claim that all roadmap functionality is implemented.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0d1e8892-aab0-4bf4-91a3-37732d26b739

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Superseded by #604 as the single canonical PRD/TRD/ADR/UML/ERD architecture path. #605's valuable additions—documentation-completeness states and current architecture/quality standards framing—have been explicitly handed to #604 along with the reusable threat-model and canonical PyO3/export-registry gaps. #604 has the broader ten-ADR, PlantUML, logical ERD, research-basis, changelog, and legacy-summary deprecation set plus one bounded OpenCode writer lease. Closing this competing authority to prevent divergent filenames/ADR numbering and duplicate CI/review churn. Do not merge separately.