Encore Health OS – Lovable Workspace Knowledge

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

1. Context

​

2. Decision order

1. Security & compliance (tenant isolation, PHI, RLS) 2. Architecture boundaries 3. Performance 4. UX 5. Code quality.

​

3. Architecture (CRITICAL)

• Every feature: owning core (e.g. RH-01, FA-01). Cores depend ONLY on PF.
• Cross-core: Platform Integration Layer (@/platform/{feature}), events, or API contracts only. No direct core imports.
• Do not change auth flow, refactor code, or add deps without explicit instruction.

​

4. Non-negotiables (NEVER)

• Missing organization_id on mutations → always .eq('organization_id', orgId).
• Reading tenant ID from user.app_metadata.organization_id → always use useOrganization() hook.
• Direct core-to-core imports → use @/platform/{feature}.
• Raw error.message to users → sanitizeErrorMessage(error).
• return null for loading → <Skeleton />.
• Direct route import for pages → React.lazy(() => import('./Page')).
• Hardcoded colors → semantic tokens only (text-success, bg-destructive).
• Schema outside migrations → all changes in supabase/migrations/.
• PHI/PII in prompts or logs → synthetic data only.
• Secrets in code → Lovable Cloud Secrets or env.
• Inline pf_user_role_assignments in edge fns → verifyOrgAccess()/verifyOrgRole() from _shared/auth.ts.
• Native dialogs → Dialog/AlertDialog/toast. Old DataTable → @/platform/table-v2. Hard-coded codes → PF-70 library. Dynamic Supabase import → static at file top.
• Modifying the realtime schema → strictly prohibited. Enforce RLS on source tables instead.

​

5. Patterns (use every time)

• Tenant: .eq('organization_id', orgId) on mutations.
• Internal cross-module links: wrap with prefixPath(path) so the active organization context is preserved.
• Form dialogs (Radix): use key={entityId ?? "new"} to force a full remount; reset state via onOpenChange.
• Routes: React.lazy + Suspense. Loading: <Skeleton />. Queries: staleTime: 5*60*1000, gcTime: 10*60*1000.
• Auth: useCurrentUser() from @/platform/auth. Supabase: static import { supabase } from '@/integrations/supabase/client'.
• Permissions: useHasPermission('module.entity.action') or <PermissionGate>; never hardcode roles.
• Dialogs: sm:max-w-md/lg/2xl/3xl/4xl with sm: prefix. Pages: <PageContainer>.
• Tables: DataTable from @/platform/table-v2. Overlays: *Dialog or *Sheet, never *Modal.
• Migrations: CLI (npx supabase); MCP for read/schema/types.ts only. Regenerate types.ts after migrations before writing hooks.
• Tailwind v4: Use @import 'tailwindcss' (not @tailwind directives). Token mapping: @theme inline { ... }. Dark mode: @custom-variant dark. Animations: tw-animate-css (not tailwindcss-animate). Gradients: prefer bg-linear-* over legacy bg-gradient-*.

​

6. DB & RLS

• All business tables: organization_id (and site_id where applicable). FORCE ROW LEVEL SECURITY on every table (defense-in-depth — applies even to table owners). UPDATE policies need WITH CHECK. Use SECURITY DEFINER helpers (e.g. pf_has_org_access()); every SECURITY DEFINER function must SET search_path = public, pg_catalog. Migrations only. custom_fields JSONB on business/transaction tables. Soft delete: partial index WHERE deleted_at IS NULL; queries .is('deleted_at', null). FK columns (including created_by/updated_by) must be indexed.

​

7. Edge functions

• Deno.serve(). Import Supabase via npm:@supabase/supabase-js@2. No @/ or src/ imports; use supabase/functions/_shared/. Auth: verifyOrgAccess()/verifyOrgRole() from _shared/auth.ts. Use getCorsHeaders(), createNotificationIfNew(), createCronHandler() etc. from _shared. deno.json: "lock": false; do not commit deno.lock.

​

8. Security & UI

• Every mutation: organization_id filter. Errors: sanitizeErrorMessage(). Secrets: Lovable Cloud Secrets. AI: via edge functions only; no PHI to AI.
• UI: semantic tokens only; <Skeleton /> for loading; <EmptyState /> for empty; <PageContainer>; mobile-first 44px touch targets.
• Formatting: user-facing dates and currency MUST use @/platform/formatting utilities. Do not use raw toLocaleString / toLocaleDateString.
• Z-index tokens: --z-base (0), --z-sticky (40), --z-dropdown (50), --z-overlay (80), --z-modal (100), --z-max (9999). Don’t hardcode arbitrary z values.

​

9. Lovable-specific

• Do not edit: client.ts, types.ts, config.toml, .env, tailwind.config.lov.json (auto-generated). Secrets in Settings > Cloud > Secrets.
• Supabase reverts: schema does not revert cleanly; after revert validate SQL. Pin version after each working feature; use Visual Edit for small UI tweaks (text, colors, spacing).
• Vite 8 (Rolldown): use inline type signatures for PreRenderedAsset/PreRenderedChunk (not rollup imports); cast sourcemap explicitly.
• Mode rules: Lovable’s Chat / Plan mode is strictly read-only — it cannot edit .ts, .tsx, .sql, OR .md files. Any prompt that asks for file edits (including doc fixes) MUST run in Default mode. If a prompt says “Chat Mode”, it means analysis only — never edits.
• 4-chat workflow for spec implementation: §1 Pre (Chat/Plan, read-only) → §2 Plan+Execute (Default throughout) → §3a Verify+Status (Default) → §3b Browser E2E (Default + browser tools). See LOVABLE_PROMPTS.md.
• Scratchpad discipline: Only .lovable/rules/ is loaded as project context. Do NOT create .lovable/plan.md or .lovable/scratch/* — both are gitignored. Pass state between chats via the handoff block at the end of each chat (paste it as the first message of the next chat).

​

10. Lovable platform features

• Run Lovable security checks before publish: RLS analysis, database security check, and dependency audit.
• Use browser testing for real user-flow verification. Trigger phrases: “verify it works”, “test this”, “check if it’s working”.
• Prefer Agent mode for larger end-to-end changes that require implementation plus verification.
• Use frontend tests (Vitest + React Testing Library) for UI rule stability.
• Use edge-function tests (Deno test runner) for backend/business-rule validation.
• Browser-testing limits: unreliable for canvas tools, uploads/downloads, right-click flows, and subtle color-detail verification.

​

11. Prompting techniques

• End complex prompts with: “Ask me any questions you need to fully understand this feature before writing code.”
• Build by component/workstream, not whole-page rewrites.
• Use real domain content; avoid placeholder text.
• Add explicit guardrails: “Do not edit X or Y; only change Z.”
• After 2-3 failed “Try to Fix” attempts, switch to Plan-mode investigation first.
• Avoid combining large implementation and browser verification in one prompt; build first, verify in follow-up.

​

12. Brand and copy rules

• Keep user-facing copy professional and clinically appropriate.
• Use sentence case for headings and action labels.
• Do not use placeholder text; use realistic behavioral-health context.
• Use US date presentation (Month Day, Year) unless feature requirements override.
• Use currency/date formatting helpers from @/platform/formatting for visible values.