Documentation

ThoughtCapture — Application Documentation

ThoughtCapture (ThoughtCapture.me) is a mobile-friendly web application for capturing thoughts via voice, text, screen recordings, or file uploads — with optional context attachments (files, links, notes) — and processing them into research insights using AI. It supports guest and authenticated users, organizes notes into thematic threads, enables public link sharing, and provides an embeddable sidebar SDK for integration into external applications.

1. Overview & Purpose

ThoughtCapture lets you capture a fleeting idea the moment it strikes — by speaking, typing, recording your screen, or uploading a file — and turns it into a structured, research-backed insight automatically. You can attach additional files, links, and context notes alongside any capture mode, and everything is processed as one unified context by the AI.

Core capabilities

  • Capture: Record audio, type text, record screen, or upload files. Each mode supports optional context attachments (additional files, links, notes) via a "+" button next to the mode toggle.
  • Transcribe: Audio and screen recordings are transcribed using speech-to-text. Uploaded files have their text extracted.
  • AI Processing: Each note gets a title, summary, key points, tags, research write-up, related concepts, reference links, and visual media — all considering the full context (transcription + attachments).
  • Threading: Multiple recordings are grouped into a single "Idea Thread" for the same topic.
  • Public Sharing: Share any thread via a public link — visitors see a read-only view without needing an account.
  • Embed SDK: Add ThoughtCapture as a sidebar widget to any external web app using a simple JavaScript SDK.
  • Dashboard: Analytics on activity, top tags, and idea highlights.
  • Guest + Authenticated modes: Guests can use the app (data stored in localStorage with a sign-in nudge); authenticated users have persistent, server-backed data.

2. Tech Stack

| Layer | Technology | |-------|-----------| | Frontend | React + Vite + Tailwind CSS | | UI Components | shadcn/ui, lucide-react icons | | Routing | react-router-dom | | Charts | recharts | | Backend | Base44 BaaS (entities, functions, integrations, auth, hosting) | | AI / Integrations | Base44 Core (InvokeLLM, TranscribeAudio, UploadFile, ExtractDataFromUploadedFile) | | Database | Base44 entities (MongoDB-backed) | | Auth | Base44 Auth (email/password, Google OAuth, OTP) | | Embed SDK | Vanilla JavaScript (IIFE), served as a static asset at /embed.js |

3. Data Model

Entity: VoiceNote

Represents a single captured thought (voice, text, screen, or upload).

| Field | Type | Description | |-------|------|-------------| | title | string | Auto-generated title from transcription | | audio_url | string | URL of uploaded audio file (voice recordings) | | file_url | string | Generic file URL for screen recordings (video) or uploaded files | | file_name | string | Original file name for uploaded files | | input_type | enum: voice, text, screen, upload | How this thought was captured | | duration_seconds | number | Recording duration in seconds | | transcription | string | Full text transcription (or typed text, or extracted file content) | | additional_files | object[] | Files attached alongside the primary capture ({file_url, file_name}) | | context_links | string[] | URLs provided by the user as reference context | | context_text | string | Additional context notes typed by the user | | summary | string | Short AI-generated summary | | key_points | string[] | Bullet points extracted by AI | | tags | string[] | Concept tags extracted by AI | | research_expansion | string | AI-generated research write-up | | related_concepts | string[] | Related concepts and references | | reference_links | object[] | Curated external links (title, url, description, source, thumbnail_url) | | media_items | object[] | Visual media (type, title, url, thumbnail_url, source) | | thread_id | string | ID of the parent IdeaThread | | status | enum: pending, processing, complete, failed | AI processing status | | recorded_at | date-time | When the note was recorded |

Built-in fields (managed by platform): id, created_date, updated_date, created_by_id.

Entity: IdeaThread

Groups multiple VoiceNotes into a thematic project.

| Field | Type | Description | |-------|------|-------------| | title | string | Thread title (auto-set from first processed note) | | summary | string | Aggregated summary | | tags | string[] | Aggregated tags from all notes in the thread | | note_count | number | Number of recordings in this thread | | last_activity | date-time | Last time a note was added or processed | | is_public | boolean | Whether this thread is publicly viewable via share link |

Entity: User (built-in)

| Field | Description | |-------|-------------| | id, email, full_name | Read-only built-in fields | | role | admin or user |

4. Application Pages & Routes

| Route | Page | Description | |-------|------|-------------| | / | Capture | Home page — record audio, type text, record screen, with optional context attachments | | /ideas | Ideas Library | Browse and search all idea threads | | /idea/:id | Idea Detail | Grid dashboard view — recordings, transcription, key points, research, media, links, share toggle, file upload | | /dashboard | Dashboard | Analytics — stats, activity chart, top topics, highlights | | /view/:id | Public Idea | Read-only public view of a shared thread (no auth required, only for is_public: true threads) | | /embed | Embed | Standalone capture interface for the sidebar SDK iframe (no app chrome) | | /integrate | Integrate | Integration guide with copy-paste embed code snippets and API reference | | /docs | Documentation | This page | | /login, /register, /forgot-password, /reset-password | Auth pages | Email/password + Google OAuth |

Page details

Capture (/)

  • Toggle between Voice and Screen input modes; a compact text input below the recorder lets you capture a thought by typing (submit with the send button or Enter).
  • Processing options: A row of toggleable AI steps (summary, key points, tags, research, references, media, related concepts, screenshots) controls which enrichment runs for each capture.
  • Context button (+): Next to the mode toggle, a "+" button opens a context panel (ContextAttachments component) where users can attach files, paste links, and type additional notes. These attachments are saved alongside the primary capture and processed as one unified context by the AI.
  • Voice: A large record button captures microphone audio; waveform visualization shows input levels.
  • Screen: Screen recorder captures screen + system audio + microphone (mixed via Web Audio API) and optionally captures periodic snapshots for visual context.
  • Sample data: New empty accounts see a "Try samples" button to seed demo idea threads.
  • On submit, a new IdeaThread is created and a VoiceNote is added with all attachments (additional_files, context_links, context_text).
  • The processVoiceNote backend function is invoked to handle AI processing asynchronously.
  • Guest note/thread IDs are stored in localStorage (tc_guest_thread_ids, tc_guest_note_ids).
  • Recent threads are shown below the capture area.

Ideas Library (/ideas)

  • Lists all threads as cards (title, summary, tags, recording count, last activity).
  • Search filters by title, summary, or tags.

Idea Detail (/idea/:id)

  • Grid dashboard layout (3 columns on desktop):
    • Left: Recordings panel — list of notes in the thread, ability to add new recordings.
    • Center: Audio player, screen recording video, uploaded file card, transcription, key points, research expansion.
    • Right: Tags, related concepts, media gallery, reference links.
  • Share button (ShareButton component): Toggles is_public on the thread. When public, shows a copyable share link (/view/:id).
  • Add file button: Uploads a file to the thread as a new note (input_type: upload), then processes it via AI.
  • Polls every 4 seconds while notes are processing to update content live.

Public Idea (/view/:id)

  • Read-only public view of a shared thread.
  • Only accessible for threads with is_public: true.
  • Shows all notes with their content (transcription, key points, research, media, references).
  • Includes a "Start your own capture thread" CTA linking to the main app.

Embed (/embed)

  • Standalone capture interface loaded in an iframe by the embed SDK.
  • Checks auth; if not signed in, shows a "Sign in" prompt (opens login in a new tab, auto-re-auths on window focus).
  • Supports voice, text, and file upload capture modes.
  • Listens for PostMessage context from the host app (setContext) to save notes to a specific thread.
  • Shows recent notes for the current context.

Integrate (/integrate)

  • Integration guide with copy-paste code snippets.
  • Shows the script tag URL, init code, setContext example, and API reference.
  • Explains SSO behavior (users must be signed in to the ThoughtCapture app).

Dashboard (/dashboard)

  • Stats: total ideas, recordings, unique tags, this week's activity.
  • 30-day activity bar chart.
  • Top topics (tag frequency).
  • Top idea highlights.

5. Backend Functions

processVoiceNote

The core AI processing pipeline. Triggered after a note is created.

Input: { noteId: string }

Pipeline:

  1. Mark as processing — updates note status to processing.
  2. Get text content — based on input_type:
    • voice: Transcribe audio via TranscribeAudio.
    • text: Use the typed text directly.
    • screen: Transcribe the screen recording's audio track.
    • upload: Extract text from the file (documents via ExtractDataFromUploadedFile, images via vision LLM).
  3. Build full context — combines transcription with:
    • context_text (user-provided notes).
    • context_links (user-provided reference URLs).
    • additional_files — text extracted from each attached file (documents extracted, images described via vision LLM).
  4. Guard — if the full context is empty or too short, sets status to failed with a descriptive message (prevents dummy content generation).
  5. Extract concepts — InvokeLLM generates title, summary, key points, and tags from the full context.
  6. Research & enrichment (parallel):
    • Research write-up (InvokeLLM with internet context).
    • Reference links from reputable sources (InvokeLLM with internet context).
    • Media items — images and videos (InvokeLLM with internet context).
    • Related concepts.
  7. Update note with all results; status set to complete.
  8. Update parent thread — aggregates tags across all complete notes, sets title/summary from first processed note, updates note_count and last_activity.

Failure handling: If transcription or file extraction fails, note status is set to failed. Empty/silent audio is rejected rather than generating dummy content. Each integration call is individually time-boxed (transcription ~2 min; concept/research/references/media/related-concepts ~90s; YouTube and file extraction ~60s) via a withTimeout wrapper, and any fatal error flips the note to failed so a recording can never get stuck in processing.

migrateToThreads

One-time data migration script that transitions standalone voice notes (without a thread_id) into organized threads.

seedDemoData

Populates the database with sample idea threads and voice notes for demonstration purposes.

6. AI Integrations (Base44 Core)

| Integration | Usage | |-------------|-------| | TranscribeAudio | Converts audio files to text (Whisper). Supports ogg, mp3, wav, webm, m4a, etc. | | InvokeLLM | Generates structured JSON or text from prompts. Supports add_context_from_internet for web search, response_json_schema for structured output, and file_urls for vision/image analysis. | | UploadFile | Uploads files to user storage, returns a file_url. | | ExtractDataFromUploadedFile | Extracts structured data from uploaded files (PDF, doc, txt, csv, json, images). |

7. Authentication & User Modes

  • Guest mode: Users can capture and view ideas without signing in. Note and thread IDs are stored in localStorage. A sign-in nudge appears at the bottom of the Capture page.
  • Authenticated mode: Users sign in via email/password or Google OAuth. Data is persisted server-side and filtered by created_by_id.
  • Auth flows: Register → OTP verification → login. Forgot/reset password supported.
  • SSO for Embed: The embed sidebar (/embed) uses the same Base44 auth session. If a user is logged in to the ThoughtCapture app, the sidebar works automatically — no separate login needed. If not signed in, the sidebar shows a "Sign in" prompt that opens the login page in a new tab; auth is re-checked when the window regains focus.
  • Auth is handled by the Base44 platform SDK (base44.auth).

8. Frontend Architecture

Key components

| Component | Purpose | |-----------|---------| | Layout | App shell — top header (logo, integrate link, docs link, user profile) + bottom navigation bar | | RecordButton | Microphone capture with live waveform visualization and duration timer | | ScreenRecorder | Screen capture with mixed mic + system audio via Web Audio API | | ContextAttachments | Panel for attaching files, links, and context text alongside any capture mode | | RecordingsPanel | Sidebar list of recordings in a thread with status indicators | | ThreadCard | Summary card for a thread (used in Ideas list and Capture recent) | | NoteCard | Summary card for a single note | | ShareButton | Toggles is_public on a thread and shows a copyable share link | | ReferenceLinks | Renders curated external links with thumbnails | | MediaGallery | Grid of images/videos with lightbox modal | | AuthLayout | Shared wrapper for login/register/forgot/reset pages | | ProtectedRoute | Route guard for authenticated pages |

State & data fetching

  • Direct SDK calls via base44.entities.<Entity>.list/filter/create/update/delete.
  • Polling for processing notes (4s interval in IdeaDetail; 10s in Ideas list).
  • Realtime subscriptions available via base44.entities.<Entity>.subscribe().

9. Embed SDK

The embed SDK (/embed.js) is a self-contained JavaScript file that turns ThoughtCapture into a sidebar widget for any external web application.

How it works

  1. Host app includes <script src="https://your-app/embed.js"></script> and calls ThoughtCapture.init().
  2. The SDK creates a floating mic button (bottom-right) and a hidden sidebar iframe.
  3. Clicking the button slides open the sidebar, which loads the /embed page.
  4. The host app can call ThoughtCapture.setContext({ threadId, projectName }) to tell the sidebar which thread to save notes to (via PostMessage).

SDK API

| Method | Description | |--------|-------------| | init(options) | Initialize the sidebar. Options: origin, width, position. Auto-detects origin from script src. | | open() | Open the sidebar. | | close() | Close the sidebar. | | toggle() | Toggle the sidebar open/closed. | | setContext({ threadId, projectName }) | Set the capture context. Notes will be saved to the specified thread. |

SSO behavior

The sidebar iframe shares the same auth session as the main app. If the user is logged in, the sidebar works immediately. If not, it shows a "Sign in" prompt.

10. Design System

  • Theme: Light/dark mode via CSS custom properties in src/index.css.
  • Typography: Inter font family.
  • Colors: Token-based (--background, --foreground, --card, --primary, etc.) mapped to Tailwind classes.
  • Radius: 0.75rem base.
  • Mobile-first: Bottom navigation bar, responsive grid layouts, max-width container.
  • Record button: Custom pulse/glow animations defined in src/index.css.

11. How to Rebuild This App

  1. Create a Base44 app with React + Vite + Tailwind CSS.
  2. Define entities:
    • VoiceNote with the schema above (mark only status as required). Include additional_files, context_links, context_text for context attachments.
    • IdeaThread with the schema above (mark title as required, include is_public).
  3. Create the processVoiceNote backend function following the pipeline in Section 5. Uses createClientFromRequest and base44.asServiceRole for SDK calls. Processes transcription + attachments as one unified context.
  4. Create the migrateToThreads function for legacy data migration.
  5. Create the seedDemoData function for demo content.
  6. Build the frontend pages:
    • Capture.jsx — voice/text/screen toggle, context attachments, note creation.
    • Ideas.jsx — thread list with search.
    • IdeaDetail.jsx — grid dashboard with audio player, transcription, AI output, share toggle, file upload.
    • Dashboard.jsx — analytics with recharts.
    • PublicIdea.jsx — read-only public view of shared threads.
    • Embed.jsx — standalone capture interface for the sidebar iframe.
    • Integrate.jsx — integration guide with code snippets.
    • Docs.jsx — this documentation page.
    • Auth pages (login, register, forgot, reset) using Base44 auth SDK.
  7. Build components — RecordButton, ScreenRecorder, ContextAttachments, RecordingsPanel, ThreadCard, ShareButton, ReferenceLinks, MediaGallery, Layout, AuthLayout.
  8. Create the embed SDK — public/embed.js (vanilla JavaScript IIFE that creates a floating button + sidebar iframe).
  9. Wire routing in App.jsx with AuthProvider, QueryClientProvider, Router, and Layout as a wrapper route. Add public routes (/view/:id, /embed) outside the Layout.
  10. Configure the design system in src/index.css and tailwind.config.js.
  11. Test the flow: capture (with attachments) → process → view in Idea Detail → share publicly → embed in external app.

12. Guest Data Storage (localStorage)

| Key | Purpose | |-----|---------| | tc_guest_thread_ids | Array of IdeaThread IDs created by a guest | | tc_guest_note_ids | Array of VoiceNote IDs created by a guest (legacy support) |

Guests' data is accessible via direct ID lookups since RLS isn't enforced for guest-created records.

This documentation is maintained as part of the application source. Update it whenever the data model, functions, or user flows change.