GhostDocs

Inspiration

Whenever projects sunset or teams reorganize, critical institutional context gets buried in dead folders of PDFs, markdown postmortems, and text logs. Organizations are often reluctant to upload confidential postmortems or financial audits into cloud RAG services due to data-leakage risks, and standard chatbots frequently hallucinate or strip away chronological causality. We wanted to prove that a zero-backend, browser-only multi-agent RAG & timeline system could be fast, verifiable, accessible, and atmospheric.

How We Built It

Frontend & Static Architecture: Next.js (output: 'export'), React 19, TypeScript (strict: true), Tailwind CSS v4, and shadcn/ui styled with custom Kiroween tokens (ghost-void, ghost-crypt, specter-, ectoplasm-, glow-, parchment-). Web Worker Pipeline: workers/parser.worker.ts runs pdfjs-dist page-by-page without blocking the UI thread (<= 50ms), while workers/embeddings.worker.ts runs 512-token overlapping chunking and Transformers.js embedding inference using zero-copy Transferable ArrayBuffer and Float32Array messages. IndexedDB Persistence: lib/db.ts defines a typed 6-table Dexie.js database (documents, chunks, embeddings, timelines, answers, capsules) with compound secondary indexes ([documentId+chunkIndex]). Property-Based & E2E Verification: 6 Vitest + fast-check test suites (100 runs per property) and 8 Playwright E2E + @axe-core/playwright accessibility test suites.

How Kiro Was Used

We used Kiro's full Spec-Driven Development workflow from Phase 0: Steering First (.kiro/steering/): Before generating a single line of code, we authored four steering constitutions (product.md, tech.md, principles.md, testing.md). Every Kiro sub-agent automatically inherited our browser-only rule, zero-hallucination citation mandate, and data-testid selector contract. Unified Master Spec (.kiro/specs/ghostdocs-master/): requirements.md: 10 EARS-syntax requirements (82 acceptance criteria), 9 Property-Based Test invariants (R-PBT-1 to R-PBT-9), and a full traceability matrix. design.md: 1,158 lines of component trees, Mermaid sequence diagrams, Dexie schemas, typed worker unions, and WCAG AA contrast tables. tasks.md: 19 top-level tasks (54 subtasks across 13 dependency waves). Kiro Hooks (.kiro/hooks/): Configured lifecycle hooks for the Document Upload pipeline, Question Asked Crew synthesis, and Time Capsule creation to enforce property tests automatically when core modules change.

Challenges We Ran Into

Keeping Main Thread Blocking Under 50ms: Running PDF text extraction, 384-dimensional vector inference, and cosine similarity over 1,000 chunks can easily freeze the browser UI. We solved this by moving all parsing and embedding into dedicated Web Workers with Transferable buffers and batching cosine similarity across requestIdleCallback slices ({ timeout: 50 }). Mathematically Guaranteeing Verbatim Citations (R-PBT-1): fast-check property testing revealed that naive whitespace splitting (split(/\s+/).join(' ')) fails exact substring checks when source documents contain newlines or multiple spaces. We engineered span-based regex slicing in extractVerbatimPassage so every citation excerpt is a guaranteed exact substring of its source chunk.

Accomplishments That We're Proud Of

True Zero Network Leakage (R-PBT-7): Proven via Content Security Policy headers and Playwright network interception tests using canary strings (ghostdocs-canary-secret-phrase-xq7z). 100% WCAG AA Compliance in a Spooky Dark Theme: Every major application state passes @axe-core/playwright with zero violations while maintaining a distinctive Kiroween aesthetic. Complete Spec-to-Test Traceability: Every requirement maps directly to a data-testid contract and automated fast-check or Playwright assertion.

What We Learned

Writing Kiro Steering documents before opening Spec mode dramatically increases the precision of Kiro's requirement detailers and task generators. Property-based testing (fast-check) pairs naturally with EARS requirements to catch subtle edge cases in text chunkers, date parsers, and vector math.

What's Next for GhostDocs

Optional WebGPU local LLM synthesis (WebLLM) alongside extractive synthesis. Peer-to-peer encrypted Time Capsule sharing over WebRTC. Additional local parsers for .docx, .pptx, and .epub archives.