Architecture & Documentation

Technical documentation covering system design, UX principles, agent thinking, and infrastructure for Second Brain.

1. Portable Architecture

The system is built around clean separation of concerns. Each layer — data, logic, AI, and UI — is independently replaceable without affecting the others. This makes the codebase maintainable, testable, and easy to extend.

Layer

Frontend

Next.js + React

Swappable → Vue 3, Remix, SvelteKit

Layer

Database

Supabase (PostgreSQL)

Swappable → MongoDB, Neon, PlanetScale

Layer

AI Layer

Anthropic Claude

Swappable → OpenAI GPT-4o, Gemini 1.5

2. Principles-Based UX

Progressive Disclosure

AI features are surfaced contextually and never forced. Users discover summarization and auto-tagging naturally at the point of creation, not through a buried settings menu.

Speed as a Feature

Skeleton loaders appear instantly during data fetching. Optimistic UI updates (e.g., card removal) precede server confirmation, making the app feel faster than it technically is.

Transparency in AI

AI-generated content (summaries, ai_tags) is clearly distinguished from user-authored content with visual indicators. Users can inspect, accept, or reject all AI suggestions.

Dark-First Design

A deep #0a0a0a background reduces eye strain during extended knowledge work sessions. Color is used purposefully — indigo for primary actions, semantic colors for type identity.

Motion with Purpose

Every animation communicates state, not decoration. Card entrance animations confirm data freshness; hover states signal interactivity; the AI panel springs open with a natural physics curve.

3. Agent Thinking

The system implements four automation patterns that actively maintain and improve the knowledge base over time, without requiring constant manual effort.

Persistent AI Enrichment: When a user generates a summary or AI tags, those are stored permanently in the database. The next time the item loads, AI enrichment is instantly available — no re-processing needed.
Separation of Tag Authority: User tags and AI tags live in separate columns. This enables future features like "items where AI and user agree on tags" — a foundation for trust scoring and quality signals.
RAG-Lite Querying: The /api/ai/query endpoint retrieves all items and passes them as structured context to Claude. This implements Retrieval Augmented Generation without a vector database.
Public API as Distribution: The GET /api/public/brain/query endpoint lets external bots and integrations query the knowledge base. The brain distributes its intelligence beyond the UI.

4. Infrastructure Mindset

Public REST API

GET /api/public/brain/query?q=your+question

Example response

{
  "question": "What do I know about machine learning?",
  "answer": "Based on your notes...",
  "sources": [
    {
      "id": "550e8400-...",
      "title": "Attention Is All You Need",
      "relevance": "Discusses transformer architecture"
    }
  ],
  "meta": {
    "total_items_queried": 24,
    "timestamp": "2026-03-15T10:00:00.000Z",
    "powered_by": "Claude AI (Anthropic)"
  }
}

Deployment Stack

Vercel

Frontend + API routes, edge CDN, CI/CD

Supabase

PostgreSQL + row-level security + realtime

Anthropic

Claude Haiku for cost-efficient AI processing

GitHub

Version control + automatic Vercel deployments

5. Full API Reference

Endpoint	Method	Description
/api/knowledge	GET	List all items — supports ?search, ?type, ?sort
/api/knowledge	POST	Create a new knowledge item
/api/knowledge/:id	GET	Fetch a single item by UUID
/api/knowledge/:id	PUT	Update an existing item
/api/knowledge/:id	DELETE	Permanently delete an item
/api/ai/summarize	POST	Generate & persist an AI summary
/api/ai/autotag	POST	Generate & persist AI tags
/api/ai/query	POST	Conversational Q&A over the knowledge base
/api/public/brain/query	GET	Public API: query the brain via ?q=