Project: paldocs
Vision
Human-facing frontend for the pal-e-docs platform. Rails 8 + Hotwire app that gives humans browser access to the same Postgres database that Claude agents access via MCP/SDK. Project pages, interactive kanban boards, and eventually full CRUD parity with the agent layer.
User Stories
- story-paldocs-kanban — interactive kanban with phase grouping and drag-and-drop
- story-paldocs-project-pages — project pages with page note rendering and activity-based sorting
- story-paldocs-auth — role-based access control via Keycloak
- story-paldocs-consolidation — absorb pal-e-docs into Rails monolith (schema, API, embeddings)
- story-paldocs-sprint-orchestration — sprint planning UI for cross-project parallel batch dispatch
Architecture
- arch-rails-views — ERB template conventions, sanitized HTML rendering, project page structure
- arch-rails-hotwire — Hotwire/Stimulus patterns (Turbo Frames, progressive enhancement, importmap registration)
- arch-rails-db — schema ownership (Rails owns migrations via structure.sql), pgvector via neighbor gem
- arch-rails-api — JSON API controllers serving the MCP-compatible REST surface
- arch-rails-jobs — Solid Queue background jobs (embedding pipeline, async operations)
- arch-keycloak-paldocs — Keycloak integration pattern for auth and visibility (pending spike #23)
- arch-mcp — MCP server transition: pal-e-mcp → new paldocs MCP server backed by Rails API
- arch-infra — k8s deployment, CI/CD pipeline, Harbor images, ArgoCD sync
Key decisions:
- Rails 8 + Hotwire — Turbo frames/streams + Stimulus for interactivity without a JS framework
- Shared Postgres — connects to
paledocsdatabase atpal-e-postgres-rw.postgres.svc.cluster.local:5432(CloudNativePG) - Rails owns schema — all migrations via ActiveRecord (structure.sql format), pgvector via neighbor gem. Replaces Alembic (decided 2026-06-22).
- Absorbs pal-e-docs — Rails serves the API, runs the embedding pipeline (Solid Queue + Ollama), and provides the UI. FastAPI is deprecated.
- CI — Woodpecker pipeline builds Docker image and pushes to Harbor
Board
Status
As of 2026-06-23:
- Prod (
paldocs.tail5b443a.ts.net) — UP - CI pipeline fixed — PR #73 merged. Stripped Bundler 4.x checksums from Gemfile.lock, downgraded BUNDLED WITH to 2.6.9 to match CI image. Follow-up ticket needed to upgrade base image to Bundler 4.x.
- Sprint 1 status: 4/5 tickets done (#49, #52, #57, #67). #50 (sprint schema) merged but validation blocked by CI — re-validate now that #73 is merged.
- Schema ownership transferred — PR #60 merged. Rails is sole migration authority.
- Consolidation sprint:1 re-cut (2026-06-23): Original 6-wave waterfall re-cut into 4 true parallel sprints per sprint philosophy. Sprint:1 = 4 parallel tickets (16pts).
- Collapsible accordion sections with updated_at sort shipped (PR #32)
- CI schema for shared pal-e-docs tables shipped (PR #34)
- CI/CD pipeline shipped (PR #21) — rubocop, rspec, docker-compose, internal Harbor, CNPG-aligned Postgres 17
- Kanban phase grouping shipped (PR #19)
- Activity trigger (PR #17) and page note rendering (PR #18) shipped
Milestones
- 2026-06-23 — Sprint:1 nearly complete: 4/5 done, CI fix merged (PR #73). Sprint re-cut from 6-wave waterfall to 4 parallel sprints.
- 2026-06-22 — Schema ownership transfer merged (PR #60). Consolidation sprint planned.
- 2026-06-07 — Kanban phase grouping (PR #19), activity trigger (PR #17), page note rendering (PR #18), worktree convention (#20), and CI/CD infrastructure (PR #21) all shipped. Board cleared.
- 2026-06-06 — Data model docs (PR #10) and infra spike (PR #16) merged. Feature tickets #11-#13 scoped and reviewed.
- 2026-05-19 — Initial scaffold, project pages, and kanban board shipped
Repos
| Repo | Platform | Role | Status |
|---|---|---|---|
| <a href="https://forgejo.tail5b443a.ts.net/ldraney/paldocs">ldraney/paldocs</a> | Forgejo | Rails frontend | Active (private) |
Note: repo was renamed from
pal-e-docs-rails to paldocs. Old Forgejo issue URLs reference the prior name.