Property PrismDev Hub

Documentation Audit and Notes (2026-02-14)

Updated Apr 3, 2026

Scope: All documentation-like files under docs/ plus root README.md, with a small number of code cross-checks where docs make “source of truth” claims (schema files, module path, route wiring, scope names).

If documentation conflicts with current SQL or backend code, treat SQL and code as authoritative.

Top Findings (High Signal)

  • All repo docs are now centralized under docs/ (with the exception of the root README.md). Index pages were added for Ops/DB/Legacy to make navigation intentional:
    • docs/ops/README.md
    • docs/database/README.md
    • docs/legacy/README.md
  • Schema drift between database/PRISM vNext.sql and database/PRISM_vNext_FINAL.sql has been eliminated: they are identical as of February 14, 2026. Keep database/PRISM vNext.sql as the canonical pointer and consider deprecating/removing the duplicate file to prevent future divergence.
  • Backend architecture and development docs were updated to match current repo reality:
    • Go module path is github.com/projectprism/api (see go-backend/go.mod).
    • Buildings are treated as PUBLIC datasets (no organization_id column in the buildings table and no org filtering for building reads), while comps/TIMs/etc are org-scoped.
    • Route wiring pattern is “construct handlers in cmd/api/main.go then handler.RegisterRoutes(r) under /api/v1”.
  • Legacy docs are quarantined under docs/legacy/ and explicitly labeled as non-authoritative. They contain real domain knowledge and historical import forensics, but they also reference a prior Next.js/Supabase workflow and stale file paths.
  • Remaining major doc gaps (still missing or not consolidated):
    • Marketing deploy/runbook (staging/prod env, Turnstile keys, analytics, caching strategy)
    • A single env-var matrix across frontend/, go-backend/, and marketing/ (what each var does, where it is used, required vs optional)
    • OpenAPI/Swagger workflow doc (how to update/verify generated artifacts, and whether frontend client generation is planned)
    • Current (non-legacy) data import runbook (what is the supported path today)
    • Production operations essentials (backup/restore, incident response, rotation policies)
  • Implementation note worth flagging (not purely “docs”, but impacts operator expectations): API key generation uses key_prefix := plainKey[:8] (see go-backend/internal/service/apikey_service.go). Because keys are prefixed with prism_live_, the stored prefix may not be uniquely identifying. If the prefix is intended to help humans distinguish keys, consider deriving it from the random segment.

Documentation Inventory (What Exists)

Line counts from wc -l:

README.md (51)

docs/README.md (76)
docs/DESIGN_SYSTEM.md (1737)
docs/frontend-pages.md (63)

docs/frontend/README.md (19)
docs/frontend/frontend-app.md (107)
docs/frontend/rebuild-plan.md (153)
docs/frontend/api-integration.md (120)
docs/frontend/navigation-ia.md (118)
docs/frontend/menu-tree-page-map.md (108)
docs/frontend/implementation-checklist.md (132)
docs/frontend/ui-style-guide.md (121)
docs/frontend/engineering-standards.md (85)
docs/frontend/maps-architecture.md (48)
docs/frontend/security-hardening.md (80)
docs/frontend/backend-api-work-items.md (71)
docs/frontend/page-backend-wiring-checklist.md (160)

docs/backend/README.md (19)
docs/backend/go-backend.md (180)
docs/backend/go-backend-architecture.md (1371)
docs/backend/go-backend-development.md (793)
docs/backend/go-backend-api-migration.md (57)
docs/backend/database-reference.md (484)
docs/backend/export-layer.md (96)
docs/backend/security-audit-2026-02-07.md (165)
docs/backend/account-profile-onboarding-guide.md (146)

docs/ops/README.md (20)
docs/ops/go-backend-runbook.md (392)
docs/ops/monitoring-stack.md (118)
docs/ops/k6-smoke-test.md (53)
docs/ops/deploy-vm-ec2.md (25)

docs/database/README.md (68)

docs/marketing/README.md (49)
docs/marketing/ARCHITECTURE.md (56)

docs/legacy/README.md (27)
docs/legacy/supabase/COMPLETE_SCHEMA_README.md (27)
docs/legacy/supabase/migrations/README.md (105)
docs/legacy/supabase/migrations/011_FIXES_APPLIED.md (84)

docs/legacy/scripts/* (various)
docs/legacy/import-logs/* (various)

docs/audit/documentation-audit-2026-02-14.md (this file)

Notes:

  • docs/legacy/import-logs/import_*.txt are run outputs, not canonical docs. They still contain useful operational facts (counts, failure causes, enum errors).
  • docs/DESIGN_SYSTEM.md, docs/backend/go-backend-development.md, and docs/backend/go-backend-architecture.md are the largest, most opinionated docs and are the most likely to drift if code changes without doc updates.

Repo-Level Docs

README.md

What it covers:

  • Repo layout and local quick-start commands for frontend and backend.
  • Canonical “source of truth” pointers:
    • database/PRISM vNext.sql
    • go-backend/
    • docs/README.md

Patterns:

  • Explicit precedence rule: if docs conflict with SQL or backend code, SQL/code win.

Gaps:

  • No single “run everything locally” guide (DB + backend + frontend + marketing), beyond per-app quick starts.
  • No consolidated env-var docs across the monorepo.

docs/README.md

What it covers:

  • The documentation index (maps Frontend, Backend, Ops, Database, Marketing, Legacy, Audit).
  • Repeats authority order (SQL/handlers are authoritative).

Patterns:

  • “Update docs in same PR” maintenance rule.

Gaps:

  • Still no dedicated OpenAPI workflow doc (it links to the right backend docs, but doesn’t define how to keep OpenAPI in sync with frontend clients).

Index / Map Docs (Navigation)

docs/frontend/README.md

  • Index for frontend rebuild docs.
  • Pattern: frontend docs are “plan + contract + route map + checklists”.

docs/backend/README.md

  • Index for backend docs.

docs/ops/README.md

  • Index for ops docs; points to where the live compose/config files actually live (go-backend/ops/, go-backend/ops/deploy/, go-backend/perf/k6-smoke.js).

docs/database/README.md

  • Canonical policy doc for schema application and incremental migrations.
  • Explicitly documents that database/PRISM vNext.sql is destructive (drops public).

docs/legacy/README.md

  • Explicit “do not treat as authoritative” warning.

Frontend Docs (Rebuild)

docs/frontend/frontend-app.md

What it covers:

  • Vite + React + TypeScript app quick start.
  • Config layout (frontend/config/* as canonical, root shims for editor/tool discovery).
  • Foundation stack decisions (TanStack Router/Query, Mantine, Clerk, Vitest/RTL, Playwright scaffolding).
  • Clerk + map 3D env var notes.

Patterns:

  • “VITE_* values are public” and “no backend API keys in frontend” repeated across docs.

Gaps:

  • No single canonical table of all frontend env vars (what each does, where it is used).

docs/frontend-pages.md

What it covers:

  • Route inventory and page content summary.

Verified against code:

  • Matches frontend/src/app/router.tsx route definitions.

Patterns:

  • Admin routes are gated (frontend gate) and expected to also be enforced server-side.

docs/frontend/rebuild-plan.md

What it covers:

  • High-level rebuild goals and migration phases.

Patterns:

  • Strong bias toward server-driven paging/filter/sort for list-heavy screens.
  • Avoid “mini dashboards” unless KPIs are actionable.

Gaps:

  • Release/cutover runbook is referenced as needed but not fully specified.

docs/frontend/api-integration.md

What it covers:

  • Backend authority order for API contracts:
    1. go-backend/internal/handler/
    2. go-backend/cmd/api/main.go
    3. generated Swagger artifacts under go-backend/docs/
  • Contract expectations: auth header behavior, error envelope expectations, list envelope expectations.

Patterns:

  • Explicit contract boundaries and consistency requirements.

Gaps:

  • OpenAPI publication/consumption strategy is not finalized in docs.

docs/frontend/navigation-ia.md and docs/frontend/menu-tree-page-map.md

What they cover:

  • Navigation grouping and IA.
  • Route mapping between old app concepts and new routes.

Drift risks:

  • Some mapping references are historical (from a prior Next.js app). These docs are still useful as intent, but treat old file paths as historical.

docs/frontend/implementation-checklist.md

What it covers:

  • Phased execution checklist with explicit backend dependencies.

Patterns:

  • Ticket-sized deliverables and explicit dependency closure.

docs/frontend/ui-style-guide.md

What it covers:

  • UX and visual rules (grid-first, calm enterprise data UI).
  • References docs/DESIGN_SYSTEM.md and implementation entry points.

Patterns:

  • Design-token discipline, Mantine-only component rule, and accessibility rules.

docs/frontend/engineering-standards.md

What it covers:

  • Frontend module boundaries and engineering conventions.

Patterns:

  • Centralized API access layer; no raw fetch in components.
  • Query key discipline; precise invalidation.

docs/frontend/maps-architecture.md

What it covers:

  • MapLibre stack decision and map component boundaries.

Gaps:

  • Backend-proxied geocoding endpoint design is mentioned as preferred, but no backend spec doc exists.

docs/frontend/security-hardening.md

What it covers:

  • Security hardening status for frontend and required backend hardening checklist.

Patterns:

  • “Fail closed” on missing Clerk config.
  • Admin routes require explicit guards.

docs/frontend/backend-api-work-items.md and docs/frontend/page-backend-wiring-checklist.md

What they cover:

  • Concrete backend endpoint and contract gaps needed to complete frontend parity.

Patterns:

  • These docs are the most “close-to-implementation” bridge between UI routes and backend endpoints.

Backend Docs (Go)

docs/backend/go-backend.md

What it covers:

  • Backend quick-start and command reference.
  • Current endpoints and major route groups.
  • CI workflow highlights.

Patterns:

  • Explicit note that Swagger artifacts can lag; handlers + route wiring are truth.

Gaps:

  • No consolidated “DB local setup” section here (that lives in docs/ops/go-backend-runbook.md and docs/database/README.md).

docs/backend/go-backend-development.md

What it covers:

  • Coding standards, file organization, and repo-accurate endpoint implementation flow.
  • DB best practices, performance/security guidelines, and review checklist.

Patterns:

  • Explicit guidance to follow code as authority.
  • Distinguishes public vs org-scoped tables in the “org filtering” guidance.

Gaps:

  • No dedicated “migrations policy” beyond docs/database/README.md (e.g., how production schema changes are reviewed/applied).

docs/backend/go-backend-architecture.md

What it covers:

  • Clean/layered architecture principles and patterns.
  • Caching strategy, scope model, auth model (JWT + API keys), and performance guidance.

Patterns:

  • “Handler -> Service -> Repository” layering.
  • Cache-aside patterns and explicit invalidation.

Drift risks:

  • This doc includes many advanced/aspirational patterns; verify against current code before implementing large changes.

docs/backend/go-backend-api-migration.md

What it covers:

  • API surface/migration notes (what route groups exist, what’s missing).

Gaps:

  • No explicit OpenAPI workflow defined (beyond “handlers are truth”).

docs/backend/security-audit-2026-02-07.md

What it covers:

  • Static code review findings and remediation plan.

Patterns:

  • Emphasis on org isolation, strict scope enforcement, and endpoint-level permission checks.

Gap:

  • A follow-up “post-fix verification” audit doc would be useful once remediations are merged.

docs/backend/account-profile-onboarding-guide.md

What it covers:

  • Clerk claim expectations, org roles, scope normalization behavior, and verification checklist.

Patterns:

  • Clear mapping of Clerk org permissions to backend scopes.

docs/backend/export-layer.md

What it covers:

  • export.* schema objects, refresh functions, and recommended access model.

Gaps:

  • No operational runbook for scheduling export refreshes (pg_cron vs external scheduler) per environment.

docs/backend/database-reference.md

What it covers:

  • Canonical reference for enums, table catalog, RLS/grants, export schema and workflows.

Patterns:

  • RLS enabled broadly, with explicit policies.
  • “Public” datasets still have RLS enabled, with permissive select policies.
  • Explicit safe view (api_keys_safe) for sensitive tables.

Ops Docs

docs/ops/go-backend-runbook.md

What it covers:

  • Local backend setup.
  • Full Docker monitoring stack (Prometheus/Alertmanager/Grafana) and Slack routing.
  • Metrics protection model in production.
  • k6 smoke gate as release threshold.

Patterns:

  • “Fail closed” Alertmanager config if Slack webhooks are missing or placeholders.

docs/ops/monitoring-stack.md

What it covers:

  • What’s in go-backend/ops/ compose stack and how to bring it up.

docs/ops/k6-smoke-test.md

What it covers:

  • Default k6 parameters and SLO thresholds.

docs/ops/deploy-vm-ec2.md

What it covers:

  • Minimal docker compose for running API container on a VM pointed at managed Postgres/Redis.

Gaps (Ops overall):

  • No production deploy runbook (beyond “run container”) covering TLS/proxy strategy, migrations, rollback, backups.

Database Docs

docs/database/README.md

What it covers:

  • Canonical schema pointer + policy for destructive rebuild vs incremental migrations.

Gaps:

  • No “how to diff schema changes” playbook (what tools, what review checklist).

Marketing Docs

docs/marketing/README.md

What it covers:

  • Marketing app quick start and env vars for SMTP lead capture.

docs/marketing/ARCHITECTURE.md

What it covers:

  • Next.js architecture conventions (SSG/ISR, Metadata API, MDX content).
  • Anti-abuse expectations (Turnstile + server-side verify + rate limiting).

Gaps:

  • No deploy/runbook (staging/prod env vars, Turnstile keys, analytics IDs, caching strategy, image hosting).

Design System

docs/DESIGN_SYSTEM.md

What it covers:

  • The canonical UI design spec: semantic tokens, typography scale, component rules, tables/maps/charts rules, accessibility and implementation checklists.

Patterns:

  • Explicit token naming and palette constraints.
  • Inter as the canonical UI font.
  • Strong emphasis on dense-but-readable data UIs and operational consistency.

Gaps:

  • No “where tokens live in code” index inside this doc (it references the stack and rules, but a short pointer list to the exact theme/token implementation files would reduce onboarding time).

Legacy Docs

Supabase Legacy (docs/legacy/supabase/*)

docs/legacy/supabase/COMPLETE_SCHEMA_README.md

  • Explicit legacy notice redirecting engineers to database/PRISM vNext.sql.
  • Pattern: clear authority order (SQL + code win).

docs/legacy/supabase/migrations/README.md

  • Migration ordering notes and “Migration 011 ready to apply”.
  • Contains legacy naming (bulk_building, audit_logs, broker) and legacy workflow assumptions (Supabase dashboard SQL editor).
  • Treat as historical unless you confirm production schema is built from these migrations.

docs/legacy/supabase/migrations/011_FIXES_APPLIED.md

  • Change log for fixes applied to migration 011.
  • Mostly useful as historical context for indexing/perf concerns.

Legacy Scripts / Import Notes (docs/legacy/scripts/*)

These docs contain a mix of valuable domain knowledge (vacancy safety, import ordering) and stale paths (prior Next.js repo file paths, Supabase-specific scripts). Treat as historical until you validate a current import pipeline.

  • docs/legacy/scripts/DATABASE_SETUP_GUIDE.md:
    • Recommends Supabase-centered schema application flows that conflict with the current “vNext rebuild SQL” approach.
  • docs/legacy/scripts/DATA_IMPORT_PLAN.md:
    • Dependency-ordered import plan, including spreadsheet anti-pattern fixes (X-marked columns, comma-separated lists -> junction tables).
    • Uses legacy table naming (bulk_building).
  • docs/legacy/scripts/IMPORT_GUIDE.md and docs/legacy/scripts/IMPORT_README.md:
    • Describes Python/Supabase import scripts and the “placeholder buildings” vacancy safety strategy.
    • References stale app code paths (for example src/lib/dashboard/calculations.ts).
  • docs/legacy/scripts/apply-vacancy-fix.md:
    • Vacancy fix notes referencing older Supabase migrations.
  • docs/legacy/scripts/FIXES_SUMMARY.md:
    • Summary of import fixes and references to specific scripts.
  • docs/legacy/scripts/SECURITY_UPGRADE.md, docs/legacy/scripts/RATE_LIMITING_SOLUTION.md, docs/legacy/scripts/IMPLEMENTATION_COMPLETE.md:
    • Read like completion reports for a prior app (Next.js middleware paths, docs references that don’t exist here).

Import Logs (docs/legacy/import-logs/*)

  • docs/legacy/import-logs/import_log.txt and docs/legacy/import-logs/import_log_fixed.txt:
    • Import run output capturing counts and specific failure causes.
  • docs/legacy/import-logs/import_final.txt:
    • Large import run output; useful for forensics (invalid enum values, connection failures, and row-level errors).

Cross-Cutting Patterns (What’s Consistent)

  • Authority order is explicit and repeated:
    • schema + handler code are authoritative
    • generated Swagger can lag
  • Multi-tenancy + scopes are a core theme:
    • org isolation for org-scoped data
    • explicit scope enforcement via middleware
    • admin-only data paths
  • Frontend rebuild emphasizes:
    • server-driven paging/filter/sort
    • typed routing and typed API wrappers
    • consistent error envelopes with request IDs
  • Ops story for backend is coherent:
    • local docker monitoring stack
    • production /metrics protection model
    • smoke load test gate with thresholds

Current Drift / Confusion Hotspots

Concrete things that can regress into doc drift:

  • Duplicate schema files:
    • database/PRISM vNext.sql and database/PRISM_vNext_FINAL.sql are currently identical.
    • Recommendation: keep exactly one canonical file long-term (or add a doc note explaining why two exist).
  • File naming with spaces:
    • database/PRISM vNext.sql requires quoting/escaping in tooling (psql -f "database/PRISM vNext.sql").
    • Recommendation: consider a space-free alias file name if tooling friction becomes real.
  • Mixed metadata conventions:
    • Many docs include Name/Description/Last Edited and sometimes Last reviewed, but ops/marketing docs do not.
    • Recommendation: standardize headers for consistency and auditability.

Missing Documentation (What You Still Don’t Have)

  • A single “run the full stack locally” guide (DB + backend + frontend + marketing) with exact prerequisites and env var list.
  • A monorepo-wide env-var reference (required vs optional, where used, which values are safe to expose).
  • Marketing deploy/runbook.
  • OpenAPI/Swagger maintenance policy (and frontend client strategy if planned).
  • Current data import runbook (non-legacy).
  • Production operations essentials:
    • backups/restore
    • migration execution policy
    • incident response / on-call expectations
    • secrets rotation policy

Suggested Follow-Ups (If You Want To Close The Gaps)

P0 (highest leverage, reduces production risk):

  • Write docs/ops/production-runbook.md covering deploy flow, TLS/proxy, backups/restore, migrations, rollback, incident response.
  • Write docs/config/env-vars.md as a single env-var matrix across frontend/, go-backend/, and marketing/.
  • Write docs/backend/openapi-workflow.md defining how Swagger artifacts are generated/checked and whether TS client generation is planned.
  • Write docs/data-import/README.md describing the supported import path today (and explicitly pointing legacy docs to docs/legacy/).

P1 (onboarding velocity):

  • Add “token implementation pointers” to docs/DESIGN_SYSTEM.md (exact theme/token file list).