docs: README, architecture diagram, and demo#15
Merged
Conversation
docs/architecture.md replaces the M0 placeholder. Covers:
- High-level component diagram (frontend, backend, governance, data, providers).
- Per-component source-of-truth file list, including invariant cross-references
(citation-or-refuse, append-only audit, redaction, FSM idempotency).
- Sequence diagrams for /query, /extract, and human review.
- ER diagram for documents → chunks → extractions → workflow_items → audit_events.
- M10 deployment shape: VPC/SG reachability graph, ECS+ALB+RDS+SSM topology,
cost posture, CD posture (workflow_dispatch only).
docs/architecture.mmd is the standalone source for the headline component
diagram. Render with mmdc:
npx -y --package=@mermaid-js/mermaid-cli mmdc \
-i docs/architecture.mmd -o docs/architecture.png \
--backgroundColor white --width 1600 --scale 2
docs/architecture.png is the committed rendering (3168x2234) so a reviewer
landing on the README sees the picture without needing to run mmdc.
…usal -> extract -> review -> dashboard) Replaces the M0 placeholder. Each step has a copy-pasteable command, an expected response shape (no fabricated metric values; real LLM output is documented as 'phrase may differ but the citation invariants are deterministic'), screenshot placeholders rooted at docs/screenshots/, and explicit invariant call-outs (citation-or-refuse, append-only audit verifiable in psql, requires_review routing). Final 'Optional - AWS' section repeats the demo against the M10 Terraform stack with a teardown reminder, but never runs apply for the reader; that remains a manual operator action documented in infra/README.md.
…tures, quickstart, eval, governance, deployment, limitations, roadmap Single-page entry point. Embeds the architecture PNG, links every sub-doc (architecture.md, demo.md, evaluation.md, guardrails.md, workflow.md, audit-and-review.md, infra/README.md), and lists every limitation honestly: synthetic data only, small eval set, eval/RESULTS.md still pending real numbers (issue #13), demo-only deployment posture, self-reported confidence is a routing signal not a calibrated probability, citation-validity is an in-context check. CI badge points at .github/workflows/ci.yml on main. License badge points at the new LICENSE file.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fa157260b8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Owner
Author
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 433d518d04
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Owner
Author
|
@codex reivew |
|
To use Codex here, create an environment for this repo. |
Owner
Author
|
yolo |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Milestone
M11 — Docs, architecture diagram, demo
Summary
Portfolio-ready documentation. Replaces the M0 placeholders in
docs/,adds a top-level
README.mdfor the GitHub landing page, ships an MITLICENSE. Docs-only — no app or infra surface changed.Definition of Done (per MILESTONES.md)
Single-page entry point with problem → architecture → features →
quickstart → evaluation → governance → deployment → limitations →
roadmap → license. Embeds the rendered architecture PNG. Links every
sub-doc. The quickstart matches
docs/demo.mdstep-for-step.docs/architecture.mmdis the LR-layout Mermaid source (76 lines).
docs/architecture.png(3168×2234) is the committed render via
mmdc 11.15.0. The rendercommand is documented in both
docs/architecture.mdand the README soa reviewer can regenerate the PNG from source without guessing.
callout in the README plus a dedicated "Limitations & synthetic-data
disclaimer" section listing every honest caveat: synthetic data only,
small eval set, pending real-provider numbers (eval: record real-provider benchmark numbers (M9 follow-up) #13), demo-only deploy
posture, self-reported confidence is a routing signal not calibrated
probability, citation-validity is an in-context check (not full
faithfulness).
What ships
README.md(new, top-level)Sections: problem, architecture (with PNG), features (capability table),
quickstart, evaluation (with the n/a-gate honesty discipline cross-ref),
governance & guardrails (citation-or-refuse, PII redaction, confidence
gating, audit invariants), deployment (M10 cost & security posture),
limitations & synthetic-data disclaimer, roadmap (M0–M11 + post-M11
backlog), project map, license. CI badge points at
.github/workflows/ci.ymlonmain.docs/architecture.md(replaces M0 placeholder)Full architectural cross-reference: high-level component diagram,
per-component source-of-truth file list with invariant cross-references,
sequence diagrams for
/query,/extract, and human review, an ERdiagram, the M10 deployment topology, and the SG reachability graph.
docs/architecture.mmd+docs/architecture.png(new)Mermaid source plus rendered PNG for the headline component diagram. LR
layout (per reviewer preference). Render command in
docs/architecture.mdand README.docs/demo.md(replaces M0 placeholder)7-step runbook: clone & start the stack → migrate & seed → query (cited
answer) → query (refusal) → extract a structured record → review/HITL
approve with audit verification in
psql→ dashboard. Optional finalsection repeats the demo on AWS using the M10 Terraform stack with a
teardown reminder. Screenshot placeholders rooted at
docs/screenshots/— capture during portfolio review.
LICENSE(new)MIT. Copyright
2026 nasr.PROGRESS.mdM11 row updated to ◐ complete on branch with DoD verification; M10 row
reads ☑ merged (PR #14).
Verification
Schema/migration concerns
None. Docs-only.
Reminder
Please squash-merge. After merge, capture screenshots from a real demo
run, drop them into
docs/screenshots/(gitignored by default — flip therule when capturing for portfolio review), then close out the post-M11
backlog: real-provider eval numbers (#13),
eval set expansion, multi-tenant + RBAC, OTel traces, production-readiness
for the AWS deploy.