Flowchart PRD

Data Model

Field	Type	Notes
`id`	string	System generated.
`short_uid`	string	System generated.
`title`	string	Required.
`hide_title`	boolean	If `true`, the title is not shown as a caption when rendered.
`description`	string	Optional.
`thumbnail`	object	Required. The flowchart image.
`mermaid_code`	string	Optional. The Mermaid source related to the thumbnail.
`license`	enum	Required. Same list of licenses used for images.
`needs_review`	boolean	”Mark for review” flag.
`confidence_score`	number	0–100.
`source_url`	string (URL)	Optional.
`linked_entities`	array	List of `{ content_id, content_type }`. Where this flowchart is attached.
`used_in_l1_ids` / `used_in_l2_ids` / `used_in_l3_ids`	array	Denormalized taxonomy usage, derived from each linked entity’s chain (`linked_entities` → Block/MCQ → Docket → L3 → L2 → L1). Powers the admin-listing filter by L1/L2/L3.
`status`	enum	`published` or `archived`.

Step 1 — Create a Flowchart

An editor creates a flowchart by filling out a form.

Required fields:

Title
Thumbnail
License (pick from the same license list as images)

Optional fields:

Description
Mermaid code (related to the thumbnail)
Mark for review (yes/no)
Confidence score (0–100)
Source URL
Hide title (yes/no) — controls whether the title shows as a caption later

Default behavior: When a flowchart is created, its status is automatically set to published.

Step 2 — Attach a Flowchart

In the Admin Panel, an editor can attach a flowchart inside the editor, either in an MCQ Solution or in Block Content.

When a flowchart is attached:

The flowchart’s linked_entities is updated with the content it was attached to, based on the content’s type (MCQ or Block) and its content_id (_id).

For a Block, the data stored is:

content — In the PlateJS editor, attaching a flowchart inserts a node: { id: xyz, type: flowchart }.
flowchart_ids — array of attached flowchart IDs.
flowchart_objects — array of the full flowchart objects.

Step 3 — Admin Listing & Rendering

Make the admin listing the same as the Image Bank.

Filter by taxonomy (L1 / L2 / L3). The listing can be filtered by L1 / L2 / L3, matching the Table Repository. The filter reads the denormalized used_in_l1_ids / used_in_l2_ids / used_in_l3_ids on the flowchart directly — no join through linked entities. A flowchart attached under multiple taxonomies appears under each: it matches when used under any of the selected L1/L2/L3 values.

Step 4 — Rendering (Client & Admin Preview)

When a flowchart needs to be shown:

Fetch the flowchart by its id.
Render the flowchart inline.
- Note: “Render inline” needs more detailing. For now, render it the same way an image is rendered.
If hide_title is not true, show the title as a caption below it.

Step 5 — Archive & Edit (Cascading Updates)

Changes to a flowchart or to a linked item must keep linkage in sync in both directions.

If a linked entity (Block or MCQ) is archived: remove that linkage from the flowchart.
Constraint — archiving a flowchart: If the flowchart is linked to more than 1 entity, do not archive it silently. Ask the editor to manually remove the links first, and show them everywhere it is currently linked.
Keep taxonomy usage in sync: whenever linked_entities changes — on attach (Step 2), on manual detach, and on the archive-cascade detach above — re-derive used_in_l1_ids / used_in_l2_ids / used_in_l3_ids through the same single write path that updates linked_entities. Block→Docket moves and Docket re-parenting do not happen (disallowed by the platform), so a linked entity’s taxonomy chain is immutable and there is no other recompute trigger.

Addendum — Taxonomy Filter (delta on executed PRD)

Added 2026-06-03. The flowchart entity shipped before this filter, so this section is a delta on the already-executed PRD.

Backfill. Existing flowcharts need used_in_l1_ids / used_in_l2_ids / used_in_l3_ids populated once from their current linked_entities (one-time migration), then maintained going forward by the Step 5 sync.
Archive-rule divergence with Table Repository — needs a decision. This PRD allows archiving a flowchart linked to ≤ 1 entity (“more than 1 → block”). The Table Repository PRD (per review) blocks archive while any linkage exists — the editor must unlink all references first. The two repositories now disagree. Decide whether to align flowchart to the stricter Table rule (block while linked_entities is non-empty) or keep flowchart as-is.