split docs into chapters

[yangm2]

reorganize Evaluation for targeted audiences

What type of PR is this? (check all applicable)

• Refactor
• Feature
• Bug Fix
• Optimization
• Documentation Update
• Infrastructure
• Maintenance

Description

Reorganize the long Architecture, Deployment and Evaluation docs so that relevant information is easier to find and digest. The files are now in ...

\- docs
   |- Architecture
   |- Deployment
   \- Evaluation

Related Tickets & Documents

• Related Issue #
• Closes #

QA Instructions, Screenshots, Recordings

Please replace this line with instructions on how to test your changes, a note on the devices and browsers this has been tested on, as well as any relevant images for UI changes.

Added/updated tests?

• Yes
• No, and this is why: only doc changes, no code
• I need help with writing tests

Documentation

• If this PR changes the system architecture, Architecture.md has been updated

[optional] Are there any post deployment tasks we need to perform?

[leekahung]

@claude pr-review

[claude]

Claude finished @leekahung's task in 1m 53s —— View job

---

PR Review: split docs into chapters

• Gather context
• Read modified config files (CLAUDE.md, README.md, PR template)
• Review Architecture docs
• Review Deployment docs
• Review Evaluation docs
• Check for broken internal links and cross-references
• Post review findings

---

Overall this is a well-executed reorganization. The audience-segmented structure in the Evaluation README is especially useful, and the runbooks in 08-debugging.md are detailed and actionable. A few broken links and stale references need fixing before merging.

Broken links

.claude/CLAUDE.md lines 9–10 — Both doc links still point to the deleted root-level files:

- **Architecture docs**: [Architecture.md](../Architecture.md)   ← 404
- **Deployment docs**: [Deployment.md](../Deployment.md)          ← 404

Should be docs/Architecture/README.md and docs/Deployment/README.md. Fix this →

.claude/CLAUDE.md line 58 — The Evaluation link was updated but has the wrong path:

See `docs/EVALUATION.md` for details.

docs/EVALUATION.md doesn't exist. Should be docs/Evaluation/README.md. Fix this →

.claude/CLAUDE.md line 54 — Code block comment still references the deleted file:

# Run evaluations (see backend/evaluate/EVALUATION.md)

Should be docs/Evaluation/README.md. Fix this →

config/README.md lines 3 and 14 — Still points to the deleted Deployment.md:

Full infrastructure details are in [Deployment.md](../Deployment.md).
See [Deployment.md — Manual server configuration changes](../Deployment.md#manual-server-configuration-changes)

Line 3 should link to docs/Deployment/README.md; line 14 should link to docs/Deployment/07-server-configuration.md (that's where manual configuration changes live now). Fix this →

Stale directory tree

docs/Architecture/02-backend-overview.md line 43 — The evaluate/ directory tree still shows the deleted file:

│   └── EVALUATION.md                   # Evaluation docs

backend/evaluate/EVALUATION.md was deleted in this PR. Remove this entry (or replace it with a pointer note). Fix this →

Misleading link display text

docs/Deployment/10-observability.md lines 20 and 35, docs/Deployment/02-environments.md line 18 — The display text says backend/evaluate/EVALUATION.md but the href correctly points to ../Evaluation/README.md. Readers clicking these won't know what they're getting:

[`backend/evaluate/EVALUATION.md`](../Evaluation/README.md)

The display text should be updated to reflect the new location, e.g. [Evaluation docs](../Evaluation/README.md).

Typos

docs/Evaluation/12-setup-and-environment.md line 47: "Deplyment details" → "Deployment details"

docs/Evaluation/12-setup-and-environment.md line 88: "(no applicable)" → "(not applicable)"

---

Positives worth calling out

• The Evaluation README's audience segmentation (legal contributors / frontend contributors / backend contributors) is excellent and will save real time for new contributors.
• The SRE runbooks in 08-debugging.md with the Detect→Diagnose→Resolve→Notify structure are production-quality.
• Mermaid diagrams are used appropriately throughout.
• 06-secrets-configuration.md flags potentially orphaned secrets (FLASK_SECRET_KEY, DB_HOST, DB_PASSWORD) — a genuinely useful cross-reference that was easy to lose in the original monolithic doc.
• The PR template was correctly updated to point to the new Architecture path.