Documentation — Second Brain

Full system context for the AI-powered knowledge platform: architecture, ingestion/query pipelines, UX principles, infrastructure, and implementation evidence.

System Overview

SecondMind captures notes, enriches them with AI, stores them in Postgres (Supabase), and lets users query their knowledge conversationally.

Ingestion
User input -> Validation -> Normalization -> Gemini summary/tags -> Save note -> Update canonical tags

Query
Question -> Query tag extraction -> DB candidate retrieval -> Relevance scoring -> Gemini answer -> Sources

Portable Architecture

SecondMind is built around strict separation of concerns. Each layer can be replaced independently without affecting the others.

Presentation

React components, pages, layouts. No business logic.

Application

Note creation flow, dashboard orchestration, Ask Brain interaction.

Service

Gemini enrichment/query logic + typed note and retrieval services.

Infrastructure

Next.js API routes, Supabase Postgres + RLS, environment and deployment boundaries.

Gemini and Supabase are isolated behind service functions (`lib/gemini.ts`, `lib/notes.ts`), making the provider and storage layers swappable.

AI Pipelines

Ingestion pipeline

Normalize raw content
Generate 2-sentence summary
Generate note-specific AI tags
Merge with manual tags
Persist note + canonical tags + note_tags relations

Query pipeline

Extract query tags
Retrieve candidates via tag/title/summary/content search
Score per note relevance
Build note-isolated context
Generate answer with explicit sources

Principles-Based UX

Capture first, organize later

Minimize friction during input. Let AI handle the structuring.

AI should clarify, not dominate

AI outputs are assistive summaries, not authoritative replacements for thought.

Progressive disclosure

Show essential information first. Details are available on demand.

Feedback builds trust

Sources are explicit and clickable. Loading and failure states are visible.

Motion guides attention

Animation directs focus, reduces cognitive load, and communicates state changes.

Agent Thinking & Self-Improvement

The system implements repeatable enrichment loops rather than a free-running agent. Updates are deterministic and traceable.

- query_logs capture question + candidate count
- note_updates track previous summary/tags during note updates
- tags/note_tags maintain reusable taxonomy and usage_count
- answer pipeline isolates note-level facts to reduce cross-note mixing

Infrastructure Mindset

Knowledge is available through API routes, not only UI components.

Implemented:
POST /api/brain/query
GET  /api/notes
POST /api/notes
GET/PATCH/DELETE /api/notes/:id
POST /api/public/brain/query

Response:
{
  "question": "...",
  "answer": "...",
  "sources": [
    { "id": "...", "title": "..." }
  ]
}

Public payload:
{
  "question": "...",
  "userId": "optional-uuid"
}