PORTAL_BUILD_PLAN.md

developer.koovira.com — Build Plan (traceability portal, not static pages)

Draft spec, 2026-09-06. Turns this developer/docs/ corpus into the searchable developer operating system described in the scope (§31–33): a developer searches "merchant cannot publish product" and gets Feature → Actors → Prereqs → Frontend → Backend → Tables → Rules → Errors → Troubleshooting → Related → Tests → ER.

Aligned with house rules: PHP + MariaDB, no CDN, no inline JS in shipped pages, config/baseconfig/config.php bootstrap, DDL only via the migration system.

Principle: content is Markdown, the portal is an index over it

The .md files in this tree stay the authoring source of truth (version-controlled, diffable, validated by _tools/). The portal indexes them into DB tables for search and traceability — it does not replace them. Regenerating the index from the .md + live schema keeps the portal honest, the same way gen_data_dictionary.php keeps the dictionary honest.

Two audiences under one subdomain

Public (devportal/index.php, already live): external API consumers. Keep as-is.
Internal (new): the engineering manual — this corpus. Login-gated (founder decision: free

intro public, the rest behind login). Reuse the existing Koovira session/auth.

Phase 0 — Content foundation (this session ✅)

Structure, methodology, validation tooling, validated architecture + finance ledger + the CommerceX exemplar. Nothing below ships value until enough modules are authored; content is the long pole.

Phase 1 — Static render of the corpus (fastest usable win)

A single gated PHP page developer/index.php that renders any developer/docs/**.md with a

left-nav tree built from the folder structure + numeric prefixes.

Add one Markdown renderer (Parsedown is a single file — none is bundled today; vendor it, no

CDN) + Mermaid rendered client-side from a locally hosted script (no CDN) for the erDiagram blocks.

Server-side full-text search over the raw .md (MariaDB FULLTEXT on an ingested table, or a

simple indexed scan) — good enough for "find the page".

Outcome: the whole manual is browsable + searchable internally.

Phase 2 — The documentation database (structured traceability)

Ingest the Markdown front-matter/tables into query-able tables (schema via the migration system, not app DDL). Proposed (prefix kvdoc_):

Table	Holds
`kvdoc_feature`	feature registry: `feature_id` (COM-004), title, module, actors, gate, entry, status
`kvdoc_feature_ref`	feature → {page file, code `path:line`, table, api, notification, test} rows
`kvdoc_error`	error registry: `error_id` (COM-E001), module, message, cause, resolution, tables, logs, severity, status
`kvdoc_error_link`	error ↔ feature, error ↔ error (related)
`kvdoc_table`	table → owning module, purpose, "written by" (reverse index)
`kvdoc_rule`	business rules `BR-*`
`kvdoc_page`	rendered page metadata + FULLTEXT body for search

Ingestion is a _tools/ script that parses the .md (the feature/error tables already have a fixed column shape) — so the DB is regenerated from the source, never hand-maintained.

Phase 3 — The traceability views

Server-rendered pages driven by the tables above:

Feature page ?feature=COM-004 → the full trace (actors, prereqs, frontend/backend, tables,

rules, errors, related features, tests, ER) assembled from kvdoc_feature*.

Error page ?error=COM-E001 → cause → tables to inspect → logs → resolution → related.
Table page ?table=orders_master → dictionary + "used by" reverse index + module ER.
Troubleshooting search — natural-language-ish query mapped to features/errors (start with

keyword match over kvdoc_error + kvdoc_feature; optionally route through Bramha later, since AI is Bramha-only by house rule).

Phase 4 — Viewers & polish

ER viewer (Mermaid, per-module + assembled system ER).
Flow viewer (render the flow blocks as diagrams).
QA traceability (link kvdoc_feature → test cases in docs/mastertesting.md).
Coverage dashboard from STATUS.md + kvdoc_* (what's documented vs what exists).
A CI/audit check (§28): compare kvdoc_table against live information_schema and flag

undocumented tables / stale row counts — the "living map" guarantee.

Effort & sequencing (honest)

Content is the bottleneck, not the portal. Phase 1 can ship in a small session; Phases 2–4

are modest once content exists. But authoring the remaining ~25 modules + auth + membership + KYC

notifications + admin to the exemplar's depth is a multi-session marathon, validated

module-by-module.

Recommended cadence: author 1–2 modules per session (finance-critical first), regenerate the

dictionary, keep STATUS.md current. Stand up Phase 1 early so the growing corpus is usable immediately; add Phases 2–3 once ~5 modules are done and the feature/error tables have enough rows to be worth querying.

Constraints to respect (validated house rules)

No CDN — vendor Parsedown + Mermaid locally.
No inline JS in shipped pages (the public devportal already follows this).
Schema only via the padmin-gated migration system (KVGuardedPDO blocks web DDL).
Login-gated internal portal; never render secrets/keys/tokens.
AI features (if any) go through Bramha, not a third-party model directly.