pal-e-docs

Plan: Browse UX Enhancements

plan-2026-02-27-browse-ux-enhancements Plan

plan completed
Project

Vision

pal-e-docs is on a resume and shown in interviews. The browse frontend must feel like a well-organized documentation hub — content surfaced by recency and relevance, project pages that tell a story, diagrams that are accurate, and access controls that let you share selectively with prospects. Not just "functional" but "this person knows how to build a knowledge system."

Projects & Repos Touched

Project/Repo Platform Role in this plan
pal-e-docs (app) Forgejo Route queries, templates, landing page mermaid diagram

Context

The Responsive Design plan made the site structurally correct on all screen sizes. But the content presentation still has UX issues:
  • Sort order: Landing page lists projects, repos, and all doc sections alphabetically. Most recently updated content should surface first — that's what visitors care about.
  • Project detail page: Clicking a project shows a feed of notes sorted by updated_at (which is good), but the project's page note (page_note_id FK) isn't pinned at the top. The project's repos aren't shown. The page is a flat list when it should tell a story.
  • Mermaid diagram: The landing page architecture diagram is wide/horizontal, making it tiny on mobile. It may also be outdated — missing repos, inaccurate connections. Needs accuracy review and a more vertical layout.
  • Demo access: No way to give prospects a login to see private documentation. Currently only one seed user. Need a demo account with managed credentials.
  • Privacy gap: 30+ notes in pal-e-platform and pal-e-services are is_public: true but contain infrastructure details (Terraform assessments, host inventories, deployment strategies) that shouldn't be public. The Phase 3 audit from plan-2026-02-25-private-notes-auth was never completed.

Previous Plan

plan-2026-02-27-responsive-design-mobile-ux — completed. This plan picks up the UX enhancements that didn't belong in the responsive design scope.

Depends On

None — all phases are independently deployable.

Decisions Made

Decision Rationale
Sort by recency EVERYWHERE, not just landing page Consistency. Landing page, dedicated list pages (/browse/projects, /browse/repos), and project detail pages all sort by recency. No alphabetical anywhere — recency is the UX principle.
Pin project page note at top of project detail The <code>page_note_id</code> FK already exists on the projects table (PR #29). The project page note is the summary/overview — it should be the first thing you see, not buried in a recency-sorted feed.
Mermaid diagram is hardcoded in landing.html, not from DB The landing page diagram is a template element, not note content. Revision means editing the template directly.
Diagram shows project-level architecture, not individual repos Repos section below the diagram already lists every repo. Diagram tells the platform story: Salt-managed host → pal-e-platform infra → pal-e-services onboarding → onboarded services.
Add <code>.tag-row</code> CSS class and apply consistently Tags displayed in flex-wrap row across all templates. Defined once in base.html, applied in project_notes.html, note.html, tag_notes.html.
Add <code>badge-planned</code> CSS class Repo status can be "planned" but had no badge style. Pre-existing gap, fixed in scope.
Fix test DB session leak <code>_get_test_db()</code> pattern across test files never closes the session generator. Harmless for in-memory SQLite but incorrect. Fixed while touching tests.
Repos on landing page can leak private project names Pre-existing issue. Tracked for Phase 3 privacy audit — repos query needs project visibility filtering.

Phases

Phase 1: Sort by recency + project detail redesign ✓ COMPLETE

Slug: phase-2026-02-27-1-recency-project-detail
Goal: ALL list pages surface recent content. Project detail page pins the project page note at top and shows related repos.
Owner: Agent (worktree, pal-e-docs repo)
Status: COMPLETE — PR #52 merged
Delivered:
  • PR #52 — Recency sort on ALL browse frontend list pages: landing (projects, repos, doc notes), /browse/projects, /browse/repos, project detail repos. Tags index stays alphabetical (correct for tags).
  • Project detail page redesign: page note content pinned at top (rendered through sanitize → autolink → wrap_tables pipeline), repos section with card grid below, notes feed excludes page note.
  • .tag-row CSS consolidated to single definition, applied consistently across note.html, tag_notes.html, project_notes.html.
  • .badge-planned CSS added (steel blue, between active green and archived gray).
  • Test DB session leak fixed — _get_test_db() generator pattern replaced with direct TestingSessionLocal() + try/finally in test_browse_ux.py, test_auth.py, test_project_schema.py.
  • SQLite timestamp format helper _sqlite_ts() for reliable sort-order testing.
  • 9 new tests in test_browse_ux.py. 161 total tests passing.
Review-fix loop: 4 rounds. Round 1: clean initial approval. Round 2: tag-row CSS undefined, no tests, repos sort inconsistency — all fixed. Round 3: duplicate CSS selector, missing landing repos test, try/finally in tests — all fixed plus SQLite timestamp format bug discovered and fixed. Round 4: clean approval.

Phase 2: Mermaid diagram revision ✓ COMPLETE

Slug: phase-2026-02-27-2-mermaid-diagram-revision
Goal: Landing page architecture diagram is accurate, vertical-oriented, and readable on mobile.
Owner: Main session (content decision) + Agent (template edit)
Status: COMPLETE — PR #57 merged
Delivered:
  • PR #57 — Replaced outdated horizontal diagram with accurate vertical-oriented architecture diagram.
  • New diagram shows 4 subgraphs: Salt-managed host, pal-e-platform (OpenTofu infra: Tailscale, Forgejo, Woodpecker, Harbor, MinIO, Monitoring), pal-e-services (ArgoCD + var.services for_each), and onboarded services (pal-e-docs, basketball-api, Pal-E).
  • CI/CD pipeline flow: Forgejo → Woodpecker → Harbor → ArgoCD.
  • Claude Config shown reading from pal-e-docs.
  • Tailscale TLS funnels shown for all public-facing services.
  • Old "Bootstrap (GitHub)" grouping removed — everything is Forgejo now.
Review-fix loop: 1 round. Clean approval — template-only change with no issues found.

Phase 3: Privacy audit + demo user → SPUN OUT

Slug: phase-2026-02-27-3-privacy-audit-demo-user
Goal: Originally: infrastructure notes are private, demo account exists, repos query filters by project visibility.
Owner: N/A
Status: SPUN OUT into plan-2026-02-28-knowledge-system-consolidation
During planning for Phase 3, scope expanded significantly beyond privacy audit into a comprehensive knowledge system consolidation: schema changes (note_type + status columns, issues table), tag taxonomy overhaul, MCP tool updates, claude-config skills migration, and repo page notes. This warranted its own plan. Privacy audit is Phase 4 of the consolidation plan. Demo user was dropped.

Key Files

Phase File Repo Change
1 ✓ <code>src/pal_e_docs/routes/frontend.py</code> pal-e-docs Recency sort on ALL list routes. Project detail: page_note + repos.
1 ✓ <code>src/pal_e_docs/templates/project_notes.html</code> pal-e-docs Page note content at top, repos section, then note feed.
1 ✓ <code>src/pal_e_docs/templates/base.html</code> pal-e-docs .tag-row consolidated, .badge-planned added.
1 ✓ <code>src/pal_e_docs/templates/note.html</code> pal-e-docs tag-row class consistency.
1 ✓ <code>src/pal_e_docs/templates/tag_notes.html</code> pal-e-docs tag-row class consistency.
1 ✓ <code>tests/test_browse_ux.py</code> pal-e-docs New — 9 tests for sort order, page note, repos.
1 ✓ <code>tests/test_auth.py</code> pal-e-docs Session leak fix.
1 ✓ <code>tests/test_project_schema.py</code> pal-e-docs Session leak fix.
2 ✓ <code>src/pal_e_docs/templates/landing.html</code> pal-e-docs Revised mermaid diagram — vertical layout, accurate architecture.

Verification

  • [x] Phase 1: ALL list pages sorted by recency. Project detail pages show page note at top + repos. .tag-row and .badge-planned CSS defined. Test sessions properly closed. 161 tests passing. PR #52 merged. 4-round review-fix loop.
  • [x] Phase 2: Mermaid diagram is accurate and vertical-oriented. Readable on mobile without lightbox. PR #57 merged. 1-round review-fix loop.
  • [x] Phase 3: Spun out into plan-2026-02-28-knowledge-system-consolidation. Privacy audit is Phase 4 there. Demo user dropped.

Next Plan Seeds

  • Role-based access control — demo user sees curated content, admin sees everything
  • Browse search bar
  • CSRF protection on login form
  • Note graph visualization (Obsidian-style)
  • project-pal-e-docs — parent project
  • plan-2026-02-27-responsive-design-mobile-ux — predecessor (completed)
  • plan-2026-02-25-private-notes-auth — Phase 3 (privacy audit) absorbed into this plan's Phase 3, then spun out to consolidation plan
  • plan-2026-02-26-browse-frontend-polish — completed predecessor
  • plan-2026-02-28-knowledge-system-consolidation — successor (Phase 3 spun out)
  • issue-pal-e-docs-recency-project-detail — resolved, Phase 1 (PR #52)
  • issue-pal-e-docs-mermaid-diagram-revision — resolved, Phase 2 (PR #57)