Curiosity Rooms

Trajectory - Engineering Spec V1

5 min read

Trajectory - Inner Map

Slug: engineering-specification-v1
Source: /Users/nitishchauhan/Downloads/Engineering Specification V1.pdf (text: ~/.cache/gemma14-sources/Engineering_Specification_V1.pdf.txt)
Index: Index - Engineering Specification V1
Constitution: CONSTITUTION - Publishable Asset Pipeline
Master: 00 - Master Index

1. Prompt spine (document as ordered design moves)

This source is a product engineering PDF, not a chat. The spine is the sequence of architecture commitments the author was locking down.

  1. S1 - Job of the system. Lightweight modular browser extension: capture conversations and webpages from many sites, stage them in a temporary queue, export reliably in multiple formats. Maintainability, extensibility, faithful preservation over feature flash.

  2. S2 - Pipeline shape. Browser → Content Script → Site Extractor → Normalized Conversation Object → Sidebar Queue (preview / edit title / remove) → Exporter (Markdown, JSON, HTML, plain text). Modules stay independent.

  3. S3 - Project layout + extractor contract. /src tree (background, content, sidebar, popup, export, extractors, storage, models, utils, hooks, assets). Per-site extractors (chatgpt, claude, gemini, grok, perplexity, cursor, plus generic) sharing canHandle(url) / extract() / normalize(). Unmatched URLs fall to Generic Extractor.

  4. S4 - Normalizer as the hard boundary. Every extractor returns different shapes; one common Conversation object erases origin. Downstream code never branches on which website produced the capture.

  5. S5 - Sidebar as temporary workspace only. View, rename, delete, multi-select, search, reorder, preview metadata. Explicit non-goals: no AI, no summaries, no tagging.

  6. S6 - Queue persistence choice. Queue must survive browser restarts. IndexedDB over chrome.storage because large conversations may exceed storage limits.

  7. S7 - Export independence + models + UI + ZIP. Export engine takes Normalized Conversation only; pluggable future exporters. Conversation / Message / Attachment / Metadata models. Popup (quick capture), Sidebar, Settings (minimal, reserved future VPS endpoint). Suggested ZIP: chat.md|json|html, meta.json, assets/images|attachments.

  8. S8 - Generic capture, errors, performance, security, standards, futures, Definition of Done. Every site still exportable; never silently discard; capture under 2s, export under 5s; no telemetry / local-first; TypeScript + composition; reserved providers; done when capture → close tab → trust without rethinking.

2. Start state

Builder mode, not essay mode. The product job (capture + queue + export) is already clear from related PRD/MVP thinking. The itch here is structural: how do you keep site-specific DOM chaos from infecting export, queue, and UI for years? Fear is not “will people use it” so much as “will one ChatGPT layout change force a rewrite of everything.” Curiosity is engineering: interfaces, boundaries, storage scale, and a Definition of Done that is cognitive trust, not feature completeness.

3. Transitions (impulses)

S1 → S2 (objective → architecture diagram)

  • Director mode: State the product in one paragraph, then freeze the data path so nothing optional sneaks into the spine.
  • Decoupling impulse: Every arrow is a module boundary; independence is the first non-negotiable.
  • Not yet solving DOM: High-level first; site mess comes after the pipe is drawn.

S2 → S3 (pipeline → folders + extractors)

  • Scaffold itch: Folder tree as a contract for Cursor or a human implementer.
  • Interface conviction: Same three methods on every site extractor; pluggable list, not a switch-soup.
  • Fallback as product guarantee: Generic Extractor means “supported” is never binary for exportability.

S3 → S4 (extractors → normalizer)

  • Content yanked (kept): Origin must die at the normalizer. Downstream ignores website brand.
  • Reject frame: “Special-case ChatGPT in the exporter” is the anti-pattern this stage exists to kill.
  • Convinced: One Conversation shape is how maintainability actually happens.

S4 → S5 (normalized object → sidebar)

  • Constraint peak: Temporary workspace only. Queue is staging, not a second brain.
  • Explicit refusals: No AI, no summaries, no tagging as engineering constraints, not roadmap teases.
  • Internal itch: If the sidebar grows brains, the product identity (faithful capture) erodes.

S5 → S6 (sidebar UX → persistence)

  • Scale realism: Large conversations blow chrome.storage; IndexedDB is the practical choice.
  • Restart trust: Queue that vanishes on restart is worse than no queue.
  • Still local: Persistence choice reinforces offline-first instincts without cloud.

S6 → S7 (storage → export, models, UI, package shape)

  • Exporter independence: Input is only Normalized Conversation; formats are plugins.
  • Model freeze: Conversation, Message, Attachment, Metadata so assets and provenance travel with the chat.
  • Minimal settings: Default format, location, auto ZIP, theme, reserved VPS endpoint later, nothing chatty.

S7 → S8 (buildable surface → reliability + done)

  • Graceful failure: Extractor → fallback; storage → retry; export fail → keep in queue; never silent discard.
  • Performance as UX: Capture under 2s, queue instant, export under 5s; avoid DOM duplication.
  • End hunt: Definition of Done as trust after close tab, not checklist vanity.

4. Inner state arc

StageState
StartNeed a maintainable capture extension architecture, not another feature laundry list
After pipelinePath is clear; independence of modules is the spine
After extractors + normalizerSite chaos contained; origin erased for all downstream code
After sidebar + queueStaging without AI; IndexedDB for conversation-scale truth
After export + modelsFormats and data shapes locked; ZIP is the portable unit
Peak / endReliability, local security, coding standards, and cognitive trust as “done”

5. Speech habits visible in this source only

  • Short imperative sentences and bullet capability lists (spec voice, not narrative chat).
  • Diagram-first thinking: vertical pipeline with branches for preview/export formats.
  • Explicit interface listing: canHandle / extract / normalize.
  • Hard refusals phrased as absences: “No AI. No summaries. No tagging.”
  • Reason attached to one-liners: “Large conversations may exceed chrome.storage limits.”
  • “Never silently discard data” as a moral line for error handling.
  • Definition of Done ends on user psychology: finish conversation, capture, close tab, trust preservation without thinking again.
  • Future hooks named as reserved interfaces that must not touch the core capture pipeline.
  • Composition over inheritance; keep website-specific logic inside extractors only.

Graph View

Backlinks