docs(architecture): document persona detection pipeline (LFXV2-2205)#1022
Conversation
Document upstream persona-service contract, BFF mapping, caching, and SSR hydration; wire cross-links from lens system and content matrix indexes. Signed-off-by: Audi Young <audi.mycloud@gmail.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdds ChangesPersona Detection Pipeline Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Pull request overview
Adds new frontend architecture documentation that explains, end-to-end, how user personas are detected and propagated through the system (upstream NATS contract → BFF detection/enrichment/caching → SSR cookie + TransferState hydration), and links it from existing lens/persona docs for discoverability.
Changes:
- Added a new “Persona Detection Pipeline” architecture doc covering the upstream
lfx-v2-persona-servicecontract, server mapping rules, caching, and SSR hydration flow. - Cross-linked the new doc from the main architecture index, the frontend architecture index, the lens system doc, and the persona × lens content matrix.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/architecture/README.md | Adds the new persona detection doc to the top-level architecture index. |
| docs/architecture/frontend/README.md | Adds “Lens & Persona System” and “Persona Detection Pipeline” entries to the frontend docs index. |
| docs/architecture/frontend/persona-detection.md | New end-to-end documentation for persona detection, mapping, caching, API endpoint shape, and SSR hydration. |
| docs/architecture/frontend/persona-content-matrix.md | Adds a pointer to the new persona detection pipeline doc for upstream context. |
| docs/architecture/frontend/lens-system.md | Adds a related link to the new persona detection pipeline doc. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
🚀 Deployment StatusYour branch has been deployed to: https://ui-pr-1022.dev.v2.cluster.linuxfound.info Deployment Details:
The deployment will be automatically removed when this PR is closed. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/architecture/frontend/persona-detection.md (1)
1-250: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winRun Prettier for this file before merge.
CI reports
Prettier/format:checkfailures on this markdown file, so this PR is currently not merge-ready on style checks.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/architecture/frontend/persona-detection.md` around lines 1 - 250, This markdown file is failing format checks, so update the document to match Prettier’s style before merging. Reformat the content in docs/architecture/frontend/persona-detection.md using the project’s standard Prettier markdown rules, preserving the existing wording and structure while correcting any spacing, wrapping, or table/list alignment issues.Source: Pipeline failures
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/architecture/frontend/persona-detection.md`:
- Around line 1-250: This markdown file is failing format checks, so update the
document to match Prettier’s style before merging. Reformat the content in
docs/architecture/frontend/persona-detection.md using the project’s standard
Prettier markdown rules, preserving the existing wording and structure while
correcting any spacing, wrapping, or table/list alignment issues.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 48e29728-d451-4df8-b114-4bfdcbebc5a1
📒 Files selected for processing (5)
docs/architecture/README.mddocs/architecture/frontend/README.mddocs/architecture/frontend/lens-system.mddocs/architecture/frontend/persona-content-matrix.mddocs/architecture/frontend/persona-detection.md
Document which project metadata fields are null vs defaulted to false on the raw personas endpoint, matching PersonaDetectionService behavior. Signed-off-by: Audi Young <audi.mycloud@gmail.com>
Fix Code Quality Checks format:check failure on persona-detection.md. Signed-off-by: Audi Young <audi.mycloud@gmail.com>
Distinguish persona vs affiliated-slugs cache eviction and describe fail-soft per-project enrichment behavior. Signed-off-by: Audi Young <audi.mycloud@gmail.com>
Signed-off-by: Audi Young <audi.mycloud@gmail.com>
Normalize markdown table column widths so format:check passes in CI. Signed-off-by: Audi Young <audi.mycloud@gmail.com>
MRashad26
left a comment
MRashad26
left a comment
There was a problem hiding this comment.
Code Review — PR #1022 docs(architecture): document persona detection pipeline (LFXV2-2205)
Overview
Adds comprehensive architecture documentation for the persona detection pipeline end-to-end: the upstream lfx-v2-persona-service NATS contract → BFF detection/enrichment services → frontend signals and cache behavior. The new persona-detection.md explains the four persona types, detection source tokens, per-project mapping logic, caching strategy (15s persona cache, de-duped by email), enrichment flow, SSR hydration via cookie, and the refresh/pin behavior on the frontend. Also updates cross-linking in lens-system.md, persona-content-matrix.md, and the main README to surface the new doc and add a detailed "Meetings write paths" section clarifying committee-writer and meetingCoordinator role gating.
Code-standards audit
Documentation PR — no code changes. No violations.
Secrets / critical-constants check ✅
No secrets or hardcoded credentials introduced.
Code quality notes
- Documentation is well-structured: upstream contract first, then BFF steps 1–7, then API shapes, then SSR/hydration, then Mermaid data-flow diagram. Follows the codebase's own patterns (e.g. links to actual service files, TypeScript interface snippets). ✅
- Cross-linking is thorough: persona-detection links to lens-system and permission-persona-navigation preread; updates to lens-system and content-matrix link back to the new doc. ✅
- "Personas are not authorization" callout at the top is clear and sets correct mental model (personas shape UX, not gating). ✅
- Caching table (15s persona, 15s slugs, 1h ROOT UID) is explicit and matches code. ✅
- Meetings write paths section is detailed: covers route guard (
writeFeature: 'meetings'), dashboard CTA (canWriteMeetings), committee tab (committee.writer), and backend OpenFGA rule. Fixes prior vague language (was "Yes" for UI gating, now specific per layer). ✅
Verdict: PASS ✅
Clear, comprehensive documentation. Ready to merge.
🧹 Deployment RemovedThe deployment for PR #1022 has been removed. |
Summary
Adds architecture documentation for how personas are detected end to end — from the upstream persona-service contract through BFF mapping, caching, and SSR hydration. Cross-links the new doc from the lens system and content matrix indexes so it is discoverable alongside related dashboard docs.