@@ -213,4 +213,193 @@ Runtime compilation with 500ms latency is better than:
213213- File watching systems
214214- Deployment complexity
215215
216- ** For dashboard authoring workflows, simplicity trumps optimization.**
216+ ** For dashboard authoring workflows, simplicity trumps optimization.**
217+
218+ ---
219+
220+ ## ⚠️ CRITICAL ARCHITECTURE DECISION ⚠️
221+
222+ ### Why We Abandoned the "Official Evidence Approach"
223+
224+ After extensive analysis, the ** Evidence + Svelte compilation approach was abandoned** because it fundamentally conflicts with runtime processing goals:
225+
226+ ** THE CORE PROBLEM: Evidence is Build-Time Architecture**
227+
228+ ### Why Evidence's Official Approach Fails for Runtime Processing:
229+
230+ 1 . ** Evidence requires builds when markdown changes** - changing a dashboard triggers full Svelte compilation
231+ 2 . ** Svelte compiler integration requires build pipeline** - cannot achieve "Edit → Refresh → See Changes"
232+ 3 . ** Evidence's reactive system depends on build-time optimization** - not compatible with runtime compilation
233+ 4 . ** File watching and hot module replacement required** - adds complexity and defeats simplicity goals
234+
235+ ### The Failed "Proper Evidence" Architecture:
236+
237+ ```
238+ ❌ Markdown → Evidence preprocessing → Svelte compiler → Build step → Executable JavaScript → Browser
239+ ↑
240+ REQUIRES BUILD ON EVERY CHANGE
241+ ```
242+
243+ ** This approach preserves 100% Evidence features but destroys the dashboard authoring experience.**
244+
245+ ### ✅ THE WORKING HYBRID ARCHITECTURE
246+
247+ ** Evidence Preprocessing + Custom Component Rendering**
248+
249+ ```
250+ ✅ Markdown → Evidence preprocessing → Component extraction → Manual rendering → Browser
251+ ↑ ↑
252+ Handles complex syntax No builds required
253+ ```
254+
255+ ### Why the Hybrid Approach Works:
256+
257+ 1 . ** Evidence preprocessing handles 90% of complexity** - markdown parsing, query extraction, template logic
258+ 2 . ** Custom component rendering provides runtime flexibility** - no builds, instant updates
259+ 3 . ** Preserves dashboard authoring workflow** - Edit → Refresh → See Changes
260+ 4 . ** Maintains Evidence feature compatibility** - SQL parameters, input components, chart interactions
261+
262+ ### Hybrid Architecture Rules:
263+
264+ - ** ✅ USE Evidence preprocessing** - leverage Evidence's robust markdown processing
265+ - ** ✅ USE custom component extraction** - regex parsing of preprocessed output
266+ - ** ✅ USE manual query execution** - runtime SQL execution via Flight SQL
267+ - ** ✅ USE placeholder replacement system** - proper component positioning
268+ - ** ❌ NO Svelte compilation** - breaks runtime processing goals
269+ - ** ❌ NO build dependencies** - destroys authoring experience
270+
271+ ### The Hard Truth: Perfect vs Good Enough
272+
273+ ** Evidence's "official approach" provides 100% feature compatibility but 0% runtime flexibility.**
274+
275+ ** The hybrid approach provides 90%+ feature compatibility with 100% runtime flexibility.**
276+
277+ ** For dashboard authoring workflows, runtime flexibility trumps perfect Evidence compatibility.**
278+
279+ ### Evidence Features Achievable with Hybrid Approach:
280+
281+ ✅ ** SQL query execution with parameters**
282+ ✅ ** Input components (Dropdown, DateRange, TextInput)**
283+ ✅ ** Chart components (BarChart, LineChart, DataTable)**
284+ ✅ ** Query chaining and template interpolation**
285+ ✅ ** Conditional logic and loops**
286+ ✅ ** Grid layouts and responsive design**
287+ ✅ ** Component interactions and filtering**
288+ ⚠️ ** Advanced Svelte reactivity** (limited but functional)
289+ ⚠️ ** Complex nested components** (requires custom handling)
290+
291+ ** This architectural decision prioritizes dashboard authoring experience over perfect Evidence compatibility - the right trade-off for this use case.**
292+
293+ ---
294+
295+ ## 🚧 CURRENT IMPLEMENTATION GAPS - TODO PLAN
296+
297+ ### Critical Issues Discovered
298+
299+ ** PROBLEM** : Template literal interpolation ` ${inputs.status_filter.value} ` not working in SQL queries
300+ - Query sent to database contains literal ` ${inputs.status_filter.value} ` instead of actual values
301+ - Evidence input components not being parsed and processed by runtime system
302+
303+ ### TODO: Evidence Feature Implementation Plan
304+
305+ #### Phase 1: Core Parameter System (HIGH PRIORITY)
306+ 1 . ** Fix SQL parameter interpolation** - template literals ` ${inputs.status_filter.value} ` not being processed
307+ 2 . ** Implement Evidence input component parsing** - parse ` <Dropdown> ` , ` <TextInput> ` , ` <DateRange> ` in runtime processor
308+ 3 . ** Add input state management** - track component values and make available to queries
309+
310+ #### Phase 2: URL and Navigation (MEDIUM PRIORITY)
311+ 4 . ** Add URL parameter handling** - Evidence input components should sync with URL state
312+ 5 . ** Implement query parameter persistence** - filter selections persist on page refresh
313+
314+ #### Phase 3: Layout and Structure (MEDIUM PRIORITY)
315+ 6 . ** Implement Evidence layout components** - ` <Grid> ` , ` <Section> ` , ` <Details> ` in hybrid renderer
316+ 7 . ** Add responsive layout support** - Evidence grid system and breakpoints
317+
318+ #### Phase 4: Logic and Control Flow (MEDIUM PRIORITY)
319+ 8 . ** Add Evidence conditional logic support** - ` {#if} ` , ` {#else} ` , ` {:else if} ` in runtime processing
320+ 9 . ** Implement Evidence loop support** - ` {#each} ` for dynamic content generation
321+ 10 . ** Add template interpolation** - ` {variable} ` display and ` ${query_name} ` query chaining
322+
323+ #### Phase 5: Documentation (LOW PRIORITY)
324+ 11 . ** Document current hybrid architecture limitations** - what Evidence features work vs don't work
325+ 12 . ** Create Evidence feature compatibility matrix** - clear guide for dashboard authors
326+
327+ ### Current Status: Partial Implementation
328+ - ✅ ** Basic Evidence preprocessing** - markdown parsing works
329+ - ✅ ** Chart components** - BarChart, LineChart, DataTable render
330+ - ✅ ** Flight SQL integration** - queries execute against DuckLake
331+ - ❌ ** Input component processing** - not parsed or functional
332+ - ❌ ** Template interpolation** - ` ${variable} ` literals not replaced
333+ - ❌ ** URL parameter handling** - no state persistence
334+ - ❌ ** Conditional logic** - ` {#if} ` blocks not processed
335+
336+ ### Next Immediate Actions
337+ 1 . Start with ** SQL parameter interpolation fix** - most critical for basic functionality
338+ 2 . Implement ** input component parsing** - required for dashboard interactivity
339+ 3 . Add ** state management system** - bridge between Evidence components and runtime
340+
341+ ** Goal** : Get basic Evidence input → SQL parameter → chart filtering workflow functional before expanding to full Evidence feature set.
342+
343+ ---
344+
345+ ## 🎯 SIMPLE STATE MANAGEMENT APPROACH - "WORSE IS BETTER"
346+
347+ ### Philosophy: Minimal Input Component Support
348+
349+ ** Goal** : Simple state store that handles dropdown filtering. Nothing fancy, just enough to make ` ${inputs.dropdown_name.value} ` work.
350+
351+ ### Implementation Plan: Simple Dropdown State Management
352+
353+ #### Core Components Needed (200-300 lines total):
354+
355+ 1 . ** Simple Inputs State Store**
356+ ``` javascript
357+ // Simple global state object
358+ const inputs = {
359+ status_filter: { value: " " },
360+ // Add more dropdowns as needed
361+ };
362+ ```
363+
364+ 2 . ** Dropdown Component Parser**
365+ - Extract ` <Dropdown name=status_filter> ` from markdown
366+ - Extract ` <DropdownOption value="Pending"> ` options
367+ - Replace with HTML ` <select> ` with event handlers
368+
369+ 3 . ** Template Interpolation Engine**
370+ - Find ` ${inputs.status_filter.value} ` in SQL queries
371+ - Replace with actual state values before sending to Flight SQL
372+ - Simple string replacement, nothing complex
373+
374+ 4 . ** Event Handling**
375+ - Listen to dropdown change events
376+ - Update inputs state object
377+ - Re-execute affected SQL queries
378+
379+ 5 . ** End-to-End Flow**
380+ ```
381+ User selects dropdown → Update inputs.status_filter.value →
382+ Replace ${inputs.status_filter.value} in SQL → Execute query → Update charts
383+ ```
384+
385+ ### TODO: Simple Dropdown Implementation
386+ 1 . ** Create simple inputs state store** - minimal state management for dropdown values
387+ 2 . ** Parse Dropdown components from markdown** - extract name and options
388+ 3 . ** Implement template interpolation** - replace ` ${inputs.dropdown_name.value} ` in SQL
389+ 4 . ** Add dropdown change event handling** - update state store on selection
390+ 5 . ** Test end-to-end** : dropdown selection → state update → SQL interpolation → query execution
391+
392+ ### Benefits of Simple Approach:
393+ - ✅ ** Minimal code** - 200-300 lines vs rebuilding Evidence
394+ - ✅ ** Works for dropdown filtering** - covers 80% of dashboard use cases
395+ - ✅ ** Easy to debug** - simple state object, basic event handling
396+ - ✅ ** Extensible** - add TextInput, DateRange later if needed
397+ - ✅ ** Preserves simplicity** - no complex reactive systems
398+
399+ ### What This WON'T Support (Acceptable Limitations):
400+ - ❌ Complex nested state
401+ - ❌ Advanced Svelte reactivity
402+ - ❌ All Evidence input types (start with Dropdown only)
403+ - ❌ Complex parameter interdependencies
404+
405+ ** This gives us the filtering functionality we need while maintaining the "worse is better" philosophy.**
0 commit comments