pal-e-docs

Convention: Client Project Structure

convention-client-project-structure Convention

onboarding active convention
Project

Convention: Client Project Structure

Every client on the pal-e platform gets four surfaces. pal-enterprises itself dogfoods the same pattern.

Rule

Every client gets four surfaces: (1) a login on pal-enterprises with a role-aware dashboard, and three URLs linked from that dashboard: (2) [business]-docs — a separate RoR repo rendering project documentation, user stories, and mermaid diagrams (plain CSS via ror-css-guide, no Tailwind), (3) [business]-agency — read-only access to their pal-e-docs project page showing kanban, tickets, and Forgejo issues, and (4) [business]-app — a RoR monolith serving the public landing page, business owner admin view, and customer dashboard. Docs are built FIRST — they are the contract between Lucas, AI, and the client. Agency comes second. App comes third.

Rationale

Docs-first means alignment before code. Before any parallel work begins, Lucas, AI agents, and the client reach shared understanding of user stories, system architecture, and project scope through the docs app. The agency surface gives the client ongoing visibility into work in progress without needing to learn developer tools. The app is a monolith because Rails makes role-gated views natural — admin and customer experiences in one repo, not separate deployments. pal-enterprises follows the identical pattern one level up: it IS the SSO gateway and dashboard for Lucas's own business, the same way each client's surfaces serve theirs.

Examples

Correct Incorrect Why
Build <code>westside-docs</code> first as a separate RoR repo with plain CSS. Align on user stories and diagrams before coding the app. Jump straight into building the Westside app and add docs later. Docs are the contract. Without alignment, parallel work drifts.
<code>westside-agency</code> links to the Westside project page in pal-e-docs. Marcus sees kanban and tickets read-only. Build a custom admin dashboard for Marcus to track project progress. pal-e-docs already has the project page and kanban. No need to rebuild it — just give scoped access.
<code>westside-app</code> is one RoR repo. Marcus logs in → admin view. Parents log in → their dashboard. Public visitors → landing page. Separate <code>westside-admin</code> and <code>westside-app</code> deployments. Rails monolith with role-gated views. One repo, one deployment, multiple experiences.
Dogfooding — pal-enterprises:
Surface pal-enterprises (Lucas) Client (e.g., Westside / Marcus)
SSO gateway <code>pal-enterprises.app</code> — prospective clients land here, submit contact form, book appointment Client logs into pal-enterprises, sees their dashboard
docs <code>pal-enterprises-docs</code> — platform vision, architecture, what pal-enterprises will be <code>westside-docs</code> — program docs, user stories, diagrams
agency <code>pal-e-agency</code> — pal-enterprises project page in pal-e-docs <code>westside-agency</code> — Westside project page in pal-e-docs
app <code>pal-enterprises.app</code> itself (the SSO gateway IS the app) <code>westside-app</code> — public landing + admin + customer views
Contact form (pal-enterprises): Mandatory fields are business name, owner's name, logo, and email. No self-serve registration — submission redirects to a calendar page to book an appointment with Lucas. Accounts are provisioned only after the appointment.
Docs app conventions:
  • Separate RoR repo per client — fresh Rails project
  • No Tailwind — uses ~/ror-css-guide (plain CSS, design tokens, mobile-first)
  • Renders markdown + mermaid diagrams
  • Behind Keycloak auth via pal-enterprises SSO
  • Client has access — this is the shared understanding, not internal docs
Kanban philosophy: A kanban session begins and ends the same day. All its tickets complete in one focused session. This avoids the overhead of context re-startup. Kanban boards in pal-e-docs are focused work sessions, not open-ended backlogs.

Enforcement

SOP-enforced — service-onboarding-sop includes the four-surface deployment as part of client provisioning. Docs-first build order is convention only — depends on discipline.
  • service-onboarding-sop — the procedure that provisions surfaces
  • project-pal-enterprises — the platform front door (dogfooding instance)
  • project-westside-basketball — reference client implementation
  • convention-kustomize-overlay — how each surface's deployment overlay is structured