Schema section — Dan's feedback & what we changed
Video: “Introduction and Search Bar Improvements.mp4”
⏱ 17:21 🎙 transcript: local Whisper (large-v3-turbo, offline) 🖼 64 frames mapped to screens 📅 processed 2026-06-25
Dan walks through the Schema section we built (Browse · Visualize · Changelog · Docs · Health) and talks through his edits. His own words at the start: «this is looking really good… take the transcript from this video and use it to generate the updates that are needed.» So this video is effectively a task log. Below, each item: what Dan said (with a timecode to re-listen), what he wants, where it stands today in the code, the case for and against, how competitors handle it from our research, and how we approached it.
How to use this. First — an overview table (every item, timecode, status, priority). Then — detailed cards, grouped by tab. The monospace timecode = the minute in the video where Dan says it. At the end — a prioritized plan and open questions for Dan.
✅ have / covered 🟡 partial 🔴 new / missing ⭐ praise (leave as-is) P0P1P2 S / M / L — effort estimate ✓ Done (shipped in code)
Overview table
| # | Timecode | Screen | What Dan wants | Status | Prior. |
|---|
| A1 | 00:22 | Browse | Search bar inside the facet dropdown (Bases / Field types…) when there are many options | ✓ Done | P1 |
| A2 | 00:35 | Panel | Descriptions in 3 tabs: Airtable · Extended · AI | ✓ Done | P0 |
| A3 | 01:17 | Panel | Search fields inside a table | ✓ Done | P1 |
| A4 | 01:31 | Panel | Config by field type (formula/options/references/lookup) | ✓ Done | P0 |
| A5 | 03:21 | Panel | Push in the Airtable tab: draft → Publish → Reset | ✓ Done | P2 |
| A6 | 04:47 | Panel | Relationships: backlink field + cardinality | ✓ Done | P0 |
| A7 | 05:56 | Cross | Expand the panel to full screen; sidebars expand/collapse | ✓ Done | P1 |
| A8 | 06:39·08:44 | Panel | Breadcrumbs: structural Base›Table›Type, reversed, clickable | ✓ Done | P0 |
| A10 | 07:55 | Cross | Visualize panel = the same (full) panel as in Browse (reuse) | ✓ Done | P1 |
| B1 | 09:25 | Visualize | Group/outline the tables of a single base | ✓ Done | P1 |
| B2 | 09:59 | Visualize | 4 relationship types + dropdown; lookup/rollup = 2 lines | ✓ Done | P0 |
| C3 | 11:27 | Changelog | Location in an entry clickable → opens the panel | ✓ Done | P0 |
| C4 | 11:50 | Panel | In the entity panel — a Changelog section for that entity | ✓ Done | P1 |
| C5 | 12:41 | Changelog | “Config changed” type + before↔after | ✓ Done | P0 |
| D1 | 13:49·16:20 | Docs | Collapse the left list — more room to write | ✓ Done | P1 |
| D2 | 14:12 | Docs | Multiple diagrams in a document | ✓ Done | P1 |
| D4 | 14:53 | Visualize→Docs | “Add to doc”: diagram snapshot into a document (modal, save/delete) | ✓ Done | P1 |
| D6 | 16:50 | Docs | Document deletion with confirmation | ✓ Done | P0 |
Separately — praise (⭐ A9 07:22, C1 11:09, D3 14:30) and housekeeping notes (C2 “I may remove the Changelog [location]”, C6 “Health — later”). Details at the end.
A · Browse + entity panel
A1 Search bar inside the facet dropdown — “and the same everywhere”
✓ Done🟡 partialP1S
What Dan said
00:22«I already mentioned adding a search bar in here to be able to filter this. Same with all of these.»
Dan's clarification (screenshot 2026-06-25): “in here” = inside the facet dropdown itself (Bases, Field types…), not a global search above the table. When there are many bases / fields / options, a search bar is needed in the popover to filter the options. “Same with all of these” = in every such dropdown.
Where it stands today
Global typeahead (EntitySearch) and facets exist. But inside the facet popover (FacetFilter) there are only “Show all / Hide all” + a list of options (radio/toggles) — there is no search field. FacetFilter.astro:53–71 (Show all/Hide all + options, no input) · SchemaBrowse.astro:108–114
Competitor patterns (our research)
- DataGrip — two-level search + abbreviation match (
fa→film_actor) + Cmd-K “Go to DB object”. - dbt docs — fuzzy, exclusion with
-, boolean OR, quoted phrases. - ⚠️ DBeaver — “search only hits expanded nodes” — our research flags this as a trap to avoid.
How we approached it
Add an
input input-sm at the top of the
FacetFilter popover that filters options in place (shown when there are more than ~8 options). Because
FacetFilter is
one shared component, this change automatically covers
all facets (Bases, Field types, Type…) = Dan's “same with all of these”. Not to be confused with A3 (searching
fields within a table) — these are different places.
Data: obtainable (facet options are already in the component). Cheap, with impact at scale.
✓ Done — where to find itThe facet popover (FacetFilter) now has a search when there are >8 options — it filters options in place. One shared component → it works for all facets (Browse + Visualize). How to check: /schema → Browse → the Field types facet (16 types) → search at the top of the popover. Code: FacetFilter.astro (data-facet-search + handler).
A2 Entity descriptions — in 3 tabs (saving space)
✓ Done🟡 partialP0S–M
What Dan said
00:38«I wonder if these descriptions are maybe three tabs… Airtable… and then your description, although I'd call it extended description… and then AI generated. So maybe three tabs you could just tab between that will save some space. And these could get pretty long, so you can maybe stretch it down.»
Where it stands today
The three sources already exist, but they are
stacked vertically, not in tabs: Airtable / AI / Your.
EntityPanel.astro:204–218✓ Decision locked (2026-06-25)
We are going with
clean 3 tabs [Airtable · Extended description · AI generated], exactly as Dan asked — saving space is the priority. Showing one source per tab (rather than all side by side) is a
deliberate choice: comparing them visually is not critical, and for pasting from AI it is enough to switch the tab. Details at the implementation stage.
Competitor patterns (our research)
- There is no direct analogue: splitting the description into “source-of-record · AI · yours” is recorded in our research as our own design, not borrowed. So this is our differentiator — the “tabs vs stacked” decision is ours to make.
How we approached it
Build 3
daisyUI tabs [Airtable · Extended description · AI generated], default Extended; rename the source; for long text — scroll/resize of the container. This is pure frontend.
Data: obtainable — the Airtable description from the meta-API; “extended” and AI are ours.
✓ Done — where to find itDescriptions in the entity panel are now 3 tabs (Airtable · Extended · AI generated, default Extended), as Dan asked. How to check: /schema → Browse → click a field → panel on the right, the Descriptions section. Code: apps/web/src/components/schema/EntityPanel.astro → renderDescriptions.
A3 Search fields inside a table
✓ Done🔴 missingP1S
What Dan said
01:17«Some tables have tons of fields. So it would be good to have a search bar in here, for the fields.»
Where it stands today
Global search exists, but there is
no scoped search across the fields of a single table — neither in the panel's Fields section nor in the Visualize side panel.
EntityPanel.astro:260–264 · SchemaCanvas.tsx:765–810Competitor patterns (our research)
- DataGrip — type-to-highlight within an object. Metaphor/DataHub — field-scoped operators
fieldPaths:. (Avoid the DBeaver trap — A1.)
How we approached it
Add a small
input input-sm above the Fields list in the panel (and in the Visualize side panel) — a filter-in-place by name/type. Cheap.
Data: obtainable (the fields are already in the model).
✓ Done — where to find itA “Filter fields…” input above the field list in the panel (appears with >7 fields), filtering in place. How to check: open the Deals table → panel → the Fields section. Code: EntityPanel.astro (children render + data-ep-filter handler).
A4 A config block depending on field type
✓ Done🟡 partialP0M
What Dan said
01:39«A formula field might have configuration information — display the formula as inline code… a single select field — display the select options… for a formula, also show what fields are referenced… if it's a lookup, there's a reference field from the same table and the lookup field from another table — we'd want the table and the field… we can get all that from the information that we have.»
Where it stands today
Single-select options
are already rendered (ghost badges). Formulas (text), “referenced fields”, structured lookup (table+field) —
missing; there is only a general
derivedFrom line “Computed from X”.
EntityPanel.astro:265–267,273–274Competitor patterns (our research)
- Stripe API reference — enum fields get a “Possible values” block (= our list of options).
- dbt docs — explicit “Depends on / Referenced by” sections (= our referenced fields).
- ChartDB / React Flow schema node — a field row = name + type (+ PK/nullable indicators).
How we approached it
Add a conditional “Configuration” block to the panel by type:
Formula → the formula text as inline code + a list of referenced fields (clickable);
Single/Multi-select → options (already there);
Lookup/Rollup → the pair “reference field (this table)” + “looked-up field (other table · field)”.
Data: obtainable — Dan says directly “we can get all that”; the Airtable meta-API returns formula, options, linked/lookup references.
✓ Done — where to find itA
CONFIGURATION block appeared in the field panel:
Formula — inline-code text +
References (clickable fields);
Lookup — “Looks up <field> in <table> via <link>”.
How to check: Deals → the
Weighted Value field (formula) or
Company Industry (lookup).
Code: EntityPanel.astro →
renderConfig; the model —
schemaEntities.ts /
SchemaCanvas.tsx (formula / referencedFieldIds / lookup*).
A5 Push to Airtable: draft → Publish → Reset
✓ Donereal write-back = V2 (backend)L
What Dan said (re-read in full)
03:21«For this push to airtable… we'll have our internal description (the three). And then I'd want, for the airtable to make this editable, in draft mode where they can make changes. And maybe they'll just copy from the AI description and paste it into there.»
04:02«We'd need a publish button… the draft will automatically save it, so we don't need a save button… so it pushes it back to airtable… and a reset button that resets it back to what is saved in airtable.»
Clarification (screenshot 2026-06-25): we move the Push button into the “Airtable” tab (into the Airtable working field/area), rather than leaving it separate at the bottom. So the editable draft becomes the Airtable description itself: Dan edits it in the Airtable tab, seeding it by copying from AI / Extended, Publish writes to Airtable, Reset returns to the live Airtable value.
✓ Done — where to find itBuilt as Dan specified. Descriptions are 2 source tabs — Airtable (Public) · Internal; the Airtable copy is the editable draft and the only one that syncs. Editing it flags a Draft badge (“Not yet published to Airtable”); Publish to Airtable runs a guarded confirm (with a stale-warning if the live value drifted) → Publishing… → Synced; Discard is the Reset (rolls back to the live Airtable value). AI is a Generate action that seeds the Airtable copy when it's blank. How to check: /schema → Browse → a field with an out-of-sync description (e.g. Deals → Stage) → the Airtable tab. Code: EntityPanel.astro → renderDescriptions. The real PATCH to Airtable (write-back + permissions) is faked client-side here and remains a V2 backend task.
AI / Extended— copy → “Airtable” tab: draft (auto-save)
Airtable draft→ Publish → writes to Airtable ／Reset → roll back to live Airtable
For
Turns our “Coming soon” into a full lifecycle spec. This is our
differentiator (two-way sync with Airtable), and it logically lives right in the Airtable tab.
Against / risk
Write-back to Airtable is a consequential action. It needs a backend (PATCH of the field description) + permissions + a confirmation/diff preview before Publish. We draw the UI now, the real push comes later.
✓ Dan answered — A5 resolved (2026-06-26)
- Airtable and Internal are separate fields. The Airtable description is the only one that syncs (user-facing); Internal is Baseout-only, can be more technical, and never syncs.
- Publish overwrites the entire Airtable field description with our saved version — shown behind a confirm (plus a stale-warning when the live value drifted); once in sync the Draft badge + Publish button disappear.
- AI is informational: it can auto-fill the Airtable description when it's blank; once there's text the user edits it manually (no auto-overwrite). AI fills the Airtable copy, not Internal.
- Field-level for now; a base-level bulk “update all descriptions at once” is explicitly deferred.
Competitor patterns (our research)
- No data in our research — no competitor with write-back is documented. This is our own V2 pattern (read-only in V1). We move without a reference — build in safety (confirmation, diff, undo).
How we approached it First settle the questions above (especially Extended vs the Airtable draft). Then: Publish/Reset in the Airtable tab, a draft badge + auto-save indicator, “Use AI / Use Extended” for seeding, a “locally changed vs published” state. The real push to Airtable is a separate V2 backend task.
Data: reading is obtainable; writing to Airtable needs a backend + permissions (not frontend).
A6 Relationships: backlink field + cardinality
✓ Done🟡 partialP0M
What Dan said
04:59«In addition to the table, I'd like to see the field that is the backlink… there really isn't a concept of link-to / linked-from, it's both ways… what we do know is if it allows for multiple links or a single link — so display like multiple, or one-to-one / one-to-many, or maybe '1+' to show it could be more than one.»
Where it stands today
We show only the
table + the word “links to / linked from”. The backlink field name is
computed but not displayed; cardinality is
missing entirely.
EntityPanel.astro:275–283 · schemaEntities.ts:202–215Competitor patterns (our research)
- Hasura — the naming “object vs array relationship” = Airtable single-vs-multiple (via
prefersSingleRecordLink) — this drives our terminology. - dbt — “Depends on / Referenced by” sections; Metabase — a “Connections” section with clickable links.
- ⚠️ Our research rejects crow's-foot notation as semantically incorrect for the two-way / many-to-many relationships of Airtable — let's not pull it in.
How we approached it
Add to the relationship row: the
backlink field name + a
cardinality badge (single → 1:1, multiple → 1:many / “1+”). The semantics — Hasura (object/array),
not crow's-foot.
Data: obtainable — the meta-API gives the inverse field id + prefersSingleRecordLink.
✓ Done — where to find itThe relationship row now shows cardinality (1:1 / 1:many, Hasura semantics, not crow's-foot) + a Backlink sub-section (the inverse field in the other table, clickable). How to check: Deals → Company (1:1, backlink “Deals”) or Companies → Deals (1:many, backlink “Company”). Code: EntityPanel.astro (relationships branch) + allowsMultiple/inverseFieldId in the model and fixture.
A7 Expand the panel to full screen; all sidebars expand/collapse
✓ Done🔴 missingP1Mcross-cutting
What Dan said
05:56«If there's a way to expand this to full screen, or at least to the menu area… there will be times where there's a lot of data to review… maybe we make all sidebars expandable and collapsible.»
Where it stands today
The panel is a fixed width
min(94vw,460px), with only Back/Close — there is
no expand button. The Visualize side panel is also a fixed 360px.
EntityPanel.astro:30–38,62–68 · SchemaCanvas.tsx:716–738Competitor patterns (our research)
- Craft — a whiteboard block “→ fullscreen”; Azimutt — collapse entities to a header; Castor — a persistent right rail. (The “expand to review large data” theme is a standard.)
How we approached it
Add an expand button to EntityPanel (content width / fullscreen) and lift it into a system pattern “expandable/collapsible side region” — the same mechanism for Docs (D1/D5). One wrapper component.
✓ Done — where to find itAn expand button (maximize/minimize) in the panel header expands it 460 → 900px for reviewing large data; clicking again contracts it. How to check: open any entity panel → the ↗ button in the header (next to ✕). Code: EntityPanel.astro (data-ep-expand + .ep-wide). Together with D1 (Docs), this is the system expand pattern.
A8 Breadcrumbs: structural Base › Table › Type, reversed, clickable
✓ Done🟡 partialP0M
What Dan said (emphasized the reversal twice)
06:39«A breadcrumb like this usually means base / table / field, but this is more like your history… it feels like it should be base / table / field. I don't know if there's a better way.»
09:00«I'd reverse it where it was base, table, then type… the opposite direction… and these should be clickable so I could click and it would go to this page. Everything is navigational between fields and bases.»
09:22«So yeah, reverse that.» — a brief, repeated emphasis on the reversal.
Where it stands today
The main breadcrumb = a
navigation history stack (push/pop, Miller-style trimming), not a structural path — which is exactly why it confuses. The segments are clickable. Separately, the title's meta line already has a static path, but it
leads with the type:
Single Line Text · Operations ▸ Tickets ▸ Subject.
EntityPanel.astro:157,236–239,290–306 now:Single Line Text · Operations ▸ Tickets ▸ Subject → reverse → target:Operations ▸ Tickets ▸ Subject(base leads; type is a trailing detail, each segment clickable)
For
A structural, reversed, clickable path = the familiar mental model; “everything navigational” aligns with C3/C4 (we link entities from everywhere).
Against / risk
We lose the convenience of “back through history”, which Dan also praised (“I like that you can click back”). Decision: the structural path is primary; keep history as a separate “back” arrow.
How we approached it
Make the main breadcrumb structural: Base › Table › Type (reversed from the current order), each segment a navigational link (schema:openEntity). Demote the history stack to a separate “back”.
✓ Done — where to find itThe panel breadcrumbs = a structural Base ▸ Table ▸ Field (base leads), ancestors clickable (navigation), the type a detail under the name; history stays on the “back” button. How to check: open any field in the panel → the breadcrumbs at the top (e.g. Sales CRM › Companies › Name). Code: EntityPanel.astro → structuralPath / renderCrumbs.
A10 Standardize the panel: Visualize = the same panel as in Browse
✓ Done🟡 consistencyP1M
What Dan said
07:55«I'd rework this to just be the same sidebar you'd see here… standardize this… cause then that will take care of everything in there… make this be the table view that matches the table view here… and it would just show all the fields.»
Resolving the ambiguity (the screenshot = the Visualize side panel): this is option (b), not (a). Dan doesn't just want to repaint the lightweight Visualize panel — he wants it to become the same (full) panel as in Browse — one component, the same information. The key: “that will take care of everything in there” + “show all the fields”. So clicking a table/field in Visualize opens the same panel with all sections (descriptions, fields, relationships, breadcrumbs), not a trimmed list.
Where it stands today
Two different panels. The Browse
EntityPanel is full (3-source descriptions, Fields, Relationships, breadcrumbs). The Visualize side panel (in the screenshot) is
lighter: a records·fields counter, Gen description + View in Health buttons, and
only a field list (no description tabs / relationships / breadcrumbs). Hence the inconsistency.
EntityPanel.astro · SchemaCanvas.tsx:716–810Competitors / principle
- This is our own design-system-first principle (one component — many contexts). No specific competitor is needed — it's system hygiene.
How we approached it
Reuse
the EntityPanel itself in Visualize (one component → both contexts), rather than keeping a separate light panel. A shared fields-view (the A3 search + the A4 config) lives
inside it. This closes A3 + A4 + A10 together.
A small ambiguity: “table view that matches” could be read narrowly as “just a field list” — but “everything in there” leans toward the full panel. If needed, we can confirm with Dan in a single sentence.
✓ Done — where to find itClicking a node in Visualize opens the same full EntityPanel (description tabs / fields / relationships / breadcrumbs), not the lightweight SidePanel — the panel is standardized everywhere. It works for all bases (the index already contains them, verified). How to check: Visualize → click any table → the right panel = as in Browse. Code: SchemaCanvas.tsx (onNodeClick → schema:openEntity; the old SidePanel removed).
B · Visualize (ER diagram)
B1 Group/outline the tables of a single base
✓ Done🔴 missingP1M–L
What Dan said
09:36«It'd be nice if we could outline the base so that all of the tables in the base are kind of grouped.»
Where it stands today
A base is only a facet filter and a label in the dropdown; the nodes are
not outlined by base; dagre lays everything out together.
SchemaCanvas.tsx:281–344,375–384Competitor patterns (our research)
- dbdiagram.io “Table Groups” — collapse/expand, colors, notes (our research: “a pattern worth adopting for chunking large bases”).
- Azimutt — named layouts, organization by “folders”.
- ⚠️ A technical note from our research: dagre can't do sub-flow/group layouts — for groups,
elkjs is needed.
How we approached it
Group a base's tables via React Flow parent/group nodes (an outlined container frame). If a group
auto-layout is needed — plan a dagre→
elkjs migration (this is a separate technical estimate).
Data: obtainable (a table's membership in a base is known).
✓ Done — where to find itBehind each base in Visualize there's a dashed container group with the base label (an overlay over the dagre layout, without changing the layout); it appears only on multi-base. How to check: Visualize → the “Sales CRM” / “Marketing” / “Operations” containers. Code: SchemaCanvas.tsx (BaseGroupNode + bbox computation in layout). Caveat: dagre doesn't cluster by base — when tables interleave, the frames may partially overlap; perfect clusters would need elkjs (as our research noted).
B2 Four relationship types + a dropdown; lookup/rollup = two lines
✓ Done🔴 missingP0L
What Dan said
10:05«Multiple types of relationships: linked records (between tables); formula (points to referenced fields, same table); lookup — that would have two lines: one to the field it references and another to the field in the other table; rollup the same. So lookup, rollup, linked record, formula — the four… those could be dropdown options.»
Where it stands today
Only linked-record edges, in
one neutral style; formula/lookup/rollup as edges are
not modeled (though a code comment does promise colors by type).
SchemaCanvas.tsx:303–329 Field— linked →Table
Formula— ref →Field (same table)
Lookup / Rollup— ref →Field (this table)+ — looks up →Field (other table)= 2 lines
Competitor patterns (our research) — a precise hit
- The Airtable “Base Schema” extension — colored edges by type, hover activation: Linked = solid gray · Formula = dashed blue · Rollup = dashed violet · Lookup = dashed orange · Count = dashed red. Our research calls this “relationship color language” the strongest reference to follow.
- React Flow schema node — field-to-field edges via per-field handles (
sourceHandle/targetHandle) — exactly the mechanism for the “two lines” of lookup/rollup. - ChartDB — cardinality markers via SVG marker defs.
How we approached it
Model the 4 types; lookup/rollup — two edges (field→source-field + source→other-table-field) via per-field handles; color coding by type (a map from the Base Schema extension); a dropdown filter “show type(s)”. This is the largest Visualize task, but the pattern is already described in our research.
Data: obtainable — formula refs and lookup/rollup source+target in the meta-API.
✓ Done — where to find it4 relationship types with color coding (linked=neutral solid · lookup=orange · rollup=violet · formula=blue, dashed) + a “Relationships” dropdown with the types (dots + toggles) for filtering. lookup/rollup → a cross-table line to the source table; formula → lines to fields of the same table. How to check: Visualize → the Relationships dropdown (hide Formula → the blue lines disappear, 26→24). Code: SchemaCanvas.tsx (RELATION/relKind, edge building, the FacetDropdown Relationships).
C · Changelog
C3 Location in an entry — clickable → opens the entity panel
✓ Done🟡 partialP0S
What Dan said
11:27«Make this location be clickable. I should be able to click on these and it brings the sidebar up of that field, like what we have in the browse. So these should all be hyperlinkable.»
Where it stands today
The change row is clickable, but it opens an
internal Changelog detail panel, not the shared
EntityPanel; the location is plain text.
SchemaChangelog.astro:126–143,426–432Competitor patterns (our research)
- A direct competitor (changelog entry → entity detail) is not in our research; the closest is Metabase, where the FK “Connections” are clickable links. This is our connective tissue between the tabs.
How we approached it
Make the location segments link to schema:openEntity (the same panel as in Browse). Cheap — the event already exists.
✓ Done — where to find itAn entry's location is now clickable (↗ on hover) → it opens the same Browse panel for the entity (stopPropagation, so as not to open the internal detail). It is active only where the entity exists in the schema (new/deleted ones are not linked — honestly). How to check: Changelog → click the location of Probability / Stage / Weighted Value. Code: SchemaChangelog.astro (data-cl-entity + handler) + entityId in the fixture.
C4 In the entity panel — a “Changelog for this entity” section
✓ Done🔴 missingP1M
What Dan said
12:03«In that field view we should have a section that shows the change log for that item. Whether it's a base or a field, the change log shows up in this area… click the field and see the full change log for that field.»
Where it stands today
In
EntityPanel there is
no history section; Changelog is a separate component and isn't imported into the panel.
EntityPanel.astro (no changelog section)Competitor patterns (our research)
- AWS Glue — a color reserved for “change-state” (our research: “a ready-made design for Changelog”). Rewind/Keepit — version/snapshot comparison (at the entity level).
How we approached it
Add a “Changelog” section to the panel = a feed filtered to this entity (from the same engine). A two-way link Changelog↔Panel (with C3).
✓ Done — where to find itA Changelog section appeared in the entity panel = a change feed filtered to this entity (a type badge + before/after); it is omitted if there are no changes. Together with C3 — a two-way link. How to check: the Stage / Probability / Weighted Value panel → the Changelog section. Code: EntityPanel.astro (renderChangelogSection + the changelog prop) — SchemaView passes it.
C5 “Config changed” type + before ↔ after
✓ Done🟡 partialP0M
What Dan said
12:48«Removed, renamed, type change… and there might be config changes — «config changed» might be one more change type — you added a new dropdown option to a single select, or modified the formula… here's your list before, or if single-select, maybe just shows the new one added.»
Where it stands today
Filter types: added / removed / renamed / typed / view — “config-changed” is
missing. But before→after already exists in the internal detail panel.
SchemaChangelog.astro:51,418–446Competitor patterns (our research)
- AWS Glue — a color for change-state. Rewind — side-by-side compare; Keepit — Snapshot Compare; Druva — Creation/Modification/Deletion types. (Our research describes the entry structure as our own engine feed.)
How we approached it
Add a
Config changed type (a new select option, a modified formula) to
TYPE_OPTS + a before↔after list (for select — highlight the addition). The before/after scaffold already exists.
Data: obtainable — a diff of the meta snapshots between backups.
✓ Done — where to find itA new Config changed type (a blue badge + a sliders icon) in the filter and the feed, with before → after. How to check: Changelog → the Config changed filter (2 entries: a Stage option; the Weighted Value formula). Code: SchemaChangelog.astro (the type union + TYPE + TYPE_OPTS) + 2 entries in the changelog fixture.
D · Docs
D1 Collapse the left list — more room to write
✓ Done🔴 missingP1S–M= A7
What Dan said (twice)
13:53«I'd like the ability to take out this area to give more room to write when editing. But I love how this works.»
16:27«Maybe there's a button to expand out so this document list shrinks. That's my only concern there, otherwise I'm loving this.»
Where it stands today
A two-pane grid fixed at
minmax(320,360) | 1fr;
no list collapse (only stacking below 900px).
SchemaDocs.astro:184–185Competitor patterns (our research)
- Craft / Notion — a clean writing mode (a centered column, a ToC rail, a minimap). Castor — a persistent right rail. Plate — edit↔read via
useReadOnly().
How we approached it
A button to collapse the left list (distraction-free writing). The same system pattern as A7 — build once, apply in the panel and in Docs.
✓ Done — where to find itA collapse button (panel-left) in the document bar hides the left list → more room to write; clicking again brings it back. How to check: Docs → open a document → the button on the left in the bar. Code: SchemaDocs.astro (data-dc-listtoggle + .dc-list-collapsed). A7 (expanding the EntityPanel itself) — still remaining.
D2 Multiple diagrams in a document
✓ Done✅ model readyP1S
What Dan said
14:25«We do want multiple diagrams — the ability to add more than one diagram… they might want multiple diagrams here.»
Where it stands today
The model is already an array:
diagrams: SchemaDocDiagram[], and they all mount. What's missing is only the
“add/remove diagram” UI (they are currently seeded from the fixture).
schemaEntities.ts:82 · SchemaDocs.astro:146–160Competitor patterns (our research)
- dbt Explorer and Eraser — “multiple diagrams per page”. Fibery — a Mermaid block renders a diagram right in the page (“the most precise reference”).
How we approached it
Storage ✅. Add a “+ Diagram” button (and delete-diagram) — it dovetails naturally with D4 (“Add to doc”).
✓ Done — where to find it“Multiple diagrams” is covered: the document model holds an array of diagrams (already ready) + the add mechanism = D4 (“Add to doc” from Visualize places a diagram into the chosen document). How to check: the D4 flow. Code: schemaEntities.ts (diagrams[]) + D4.
D4 “Add to doc”: a diagram snapshot from Visualize into a document
✓ Done🔴 missingP1L
What Dan said
14:53«From the visualize, a button «add to doc» → a dropdown of existing docs with an option to create new. If new, it comes here already with whatever's in the visualize… take a snapshot of it and put it in a doc… maybe it opens in a modal to edit that version… need the ability to save it back… and to delete it from the doc.»
⚠️ UX decision (concern 2026-06-25): NOT a navigation to the Visualize tab
The current “Open in Visualize”
navigates to the Visualize tab (
href="/schema") — the user
loses context, jumping back and forth. Instead, we open
both the viewing and the editing of a diagram from a doc
in an overlay over the doc,
without changing the tab. Recommendation: a
tall bottom fly-out / sheet (~85vh) that slides up from the bottom (the doc visible above, the full width for a wide ER diagram)
+ a fullscreen button for deep editing; closing → returns to the same place in the doc. This aligns with Dan's “opens in a modal” (drawer and modal here are the same in-place overlay).
Where it stands today
Missing. Diagrams are seeded from the fixture; in Docs there is only a
static link “Open in Visualize” (href="/schema" — exactly the navigation that loses context); in Visualize there is Export (PNG/PDF/JSON/CSV, not yet functional), but no “Add to doc”.
SchemaDocs.astro:152 · SchemaCanvas.tsx:544–558 Visualize→ “Add to doc”→ dropdown: existing / new→ snapshot (toObject)→ overlay over the doc (fly-out / modal)→ Save back／Delete from doc
Competitor patterns (our research)
- Whimsical / Eraser — a saved diagram block: view-only in the doc, edit in the source, expand-to-fullscreen.
- Fibery — a saved mini-diagram in the page; Craft — whiteboard→fullscreen.
- React Flow
toObject() (nodes/edges/viewport) — exactly the “snapshot & restore” mechanism for a saved view.
How we approached it
An “Add to doc” button in Visualize → a dropdown of existing docs (plus a “New document” option) → a snapshot via
toObject() → a diagram instance in the doc = a
view-only block; “Expand/Edit” opens an
in-place overlay (bottom fly-out + fullscreen,
without a route change) → save back / delete. We replace the current navigational “Open in Visualize” with this same overlay. It dovetails with D2.
Data: obtainable — these are our own diagrams (nothing external).
✓ Done — where to find itAn “Add to doc” button on the Visualize toolbar → a bottom fly-out drawer (a new Drawer side="bottom" variant, registered in the storybook) → choose a document (existing + “New document”) → Add → a confirmation “✓ Diagram added to …” + close. In-place, without switching tabs (my UX decision + Dan's “opens in a modal”). How to check: Visualize → “+ Add to doc”. Code: SchemaView.astro (Drawer + script) · SchemaCanvas.tsx (the button) · Drawer.astro (the bottom variant).
D6 Document deletion with confirmation
✓ Done🔴 missingP0S
What Dan said
16:50«We probably need a delete option as well to delete documents, with a confirmation as well.»
Where it stands today
There is “New”, but
no deletion at all.
SchemaDocs.astro:75,83,387–398Competitors / principle
- A standard destructive pattern (our
interface-rules: confirmation for irreversible actions). No separate competitor is needed.
How we approached it
Delete-doc + a daisyUI modal confirmation (a red button, the doc name in the text). Quick.
✓ Done — where to find itA red trash button in the document bar → a daisyUI modal with the name → Delete removes it, the counter updates, the next one opens (or an empty state). How to check: Docs → open a document → the trash on the right in the bar. Code: SchemaDocs.astro (data-dc-delete + the modal + deleteCurrent).
⭐ Praise & housekeeping notes (what NOT to touch / parked)
Praise — left as is
07:22 · A9«I do like this view.» / «Oh that's awesome. Well done. That's cool. That's great.» — a positive reaction (likely on opening Visualize/relationships).
11:09 · C1«How you did this is fine — if it's added, there isn't a before and after, so that makes sense.» — confirmed the current “added without diff” logic.
14:30 · D3«I love the open and visualize… perfect. Brings those up. That's awesome.» — the doc→visualize behavior approved.
16:34«Otherwise I'm loving this. This is going to be amazing. This is a really useful tool. That is looking great.» — an overall assessment of the section.
Housekeeping notes
- C2 (11:21): «I might remove [the changelog location] in the product» — Dan is not sure himself, so we keep it for now. Not a priority.
- C6 (13:48): «Health will revisit» — Dan deliberately deferred the Health tab. We don't touch it this round.
Prioritized plan
P0 — the core of the round (high value, data obtainable now)
- P0A2 Descriptions in 3 tabs + renaming Extended S–M
- P0A4 Config by field type (formula/references/lookup) M
- P0A6 Relationships: backlink field + cardinality (Hasura semantics) M
- P0A8 Structural, reversed, clickable breadcrumbs M
- P0B2 4 relationship types + colors + dropdown; lookup/rollup = 2 lines L
- P0C3 Changelog location → opens the panel S
- P0C5 “Config changed” type + before↔after M
- P0D6 Document deletion + confirmation S
P1 — strong reinforcement
- P1A1 Search bar inside the
FacetFilter popover (one component → all facets) S - P1A10 Reuse the full
EntityPanel in Visualize (+ inside, a shared fields-view with the A3 search / A4 config) M - P1A7 + D1 A system expand/collapse pattern (panel + Docs in one solution) M
- P1C4 A Changelog section in the entity panel M
- P1B1 Grouping a base's tables (estimate dagre→elkjs) M–L
- P1D4 + D2 “Add to doc” snapshot + multiple diagrams (add UI) L
P2 / backend / parked
- P2A5 Push to Airtable (draft/Publish/Reset) — UI now, write-back needs a backend L
- P2Global search polish — abbreviation-match (DataGrip), a Cmd-K palette S
- P2C2 the fate of the Changelog location — Dan's decision · Health — deferred by Dan
Open questions for Dan
- A5 (please clarify!): Is “Extended/Your” the same as the published Airtable draft, or different fields? · Does Publish overwrite the entire description? Do we show before→after? · “Use AI/Extended” buttons or manual copying? · only fields or also tables/bases? · the scope of the backend write-back for V2 (details in the A5 card).
- A8: we make the structural path primary — do we keep navigation history as a separate “back” arrow?
- B1: base grouping — do we need a group auto-layout (then we plan a dagre→elkjs migration), or is a static outline frame enough?
- D4: “edit version in modal” — is the diagram in the doc an independent snapshot (Whimsical-style: view-only in the doc, edit separately), or always a live copy of the schema?