Architecture & Documentation

A deep dive into the architectural decisions, design principles, and infrastructure that power Second Brain.

Portable Architecture

Second Brain is built with a layered architecture that maintains clear separation of concerns. Each layer can be swapped independently without affecting others.

Presentation Layer

React components with Next.js App Router. Swappable with any React framework or even a mobile app consuming the same API.

API Layer

Next.js API routes exposing RESTful endpoints. Can be replaced with Express, FastAPI, or any HTTP framework. Routes are thin — they validate input and delegate to services.

AI Service Layer

Abstraction layer with provider interface. Supports OpenAI, Gemini, and Ollama with automatic fallback chain. Adding a new provider requires implementing one interface with 4 methods.

Data Layer

Prisma ORM with PostgreSQL. The schema is database-agnostic via Prisma — switching to MySQL, SQLite, or MongoDB requires only a datasource change.

AI Provider Interface

interface AIProvider {
  summarize(content: string): Promise<string>;
  autoTag(content: string, existingTags: string[]): Promise<string[]>;
  query(question: string, context: string): Promise<string>;
  generateEmbedding(text: string): Promise<number[]>;
}

// Adding a new provider:
export class AnthropicProvider implements AIProvider {
  // Implement 4 methods — done!
}

Principles-Based UX

Every AI interaction in Second Brain is guided by these five design principles:

1

Progressive Disclosure

AI features are opt-in, not forced. Users choose when to auto-summarize or auto-tag. The interface starts simple and reveals complexity on demand.

2

Contextual Intelligence

AI suggestions appear where they're relevant — tag suggestions during capture, summaries in detail views, conversational queries in the dashboard. AI augments the workflow, never interrupts it.

3

Graceful Degradation

The app remains fully functional without AI. If all providers are unavailable, users can still capture, organize, and search their knowledge manually. AI enhances but isn't required.

4

Consistent Feedback

Every action has visual confirmation — toast notifications for saves, loading spinners for AI processing, skeleton loaders for data fetching. Users always know the system state.

5

Keyboard-First Power

Power users can navigate entirely via keyboard. Cmd+K opens the command palette, shortcuts exist for common actions, and focus management follows WAI-ARIA patterns.

Agent Thinking

Second Brain implements autonomous background processes that maintain and improve the knowledge base over time:

Auto-Tagging Agent

When a new knowledge item is created with the auto-tag option enabled, the system analyzes the content and suggests relevant tags. It prefers existing tags to maintain consistency, but creates new ones when the content introduces novel concepts.

Summarization Agent

On-demand summarization generates concise 2-3 sentence summaries of knowledge items. Summaries are stored and can be regenerated if the content is updated, ensuring they stay current.

Embedding Agent

Vector embeddings are generated for each knowledge item, enabling semantic search. When content is updated, embeddings are regenerated to maintain search accuracy. The embedding model is configurable per provider.

Query Agent

The conversational query system acts as an intelligent retrieval agent. It receives a question, searches the knowledge base for relevant context, and synthesizes an answer citing specific sources. It's available both through the UI and the public API.

Infrastructure Mindset

Second Brain exposes its intelligence through a public API and embeddable widget, enabling external systems to access your knowledge base.

Public API

Query your knowledge base programmatically:

# Query the knowledge base
curl "https://your-app.vercel.app/api/public/brain/query?q=What%20do%20I%20know%20about%20React%20hooks"

# Response
{
  "answer": "Based on your notes, React hooks allow...",
  "sources": [
    {
      "id": "clx123",
      "title": "React Hooks Deep Dive",
      "excerpt": "useEffect manages side effects..."
    }
  ],
  "timestamp": "2026-02-07T12:00:00Z"
}

Embeddable Widget

Embed a search widget on any website:

<!-- Add to any HTML page -->
<iframe
  src="https://your-app.vercel.app/embed"
  width="400"
  height="500"
  frameborder="0"
  style="border-radius: 12px; border: 1px solid rgba(255,255,255,0.06);"
></iframe>

Knowledge API Endpoints

GET/api/knowledgeList items (auth required)
POST/api/knowledgeCreate item (auth required)
GET/api/knowledge/:idGet item (auth required)
PUT/api/knowledge/:idUpdate item (auth required)
DELETE/api/knowledge/:idDelete item (auth required)
POST/api/ai/summarizeSummarize content (auth required)
POST/api/ai/auto-tagAuto-tag content (auth required)
POST/api/ai/queryQuery knowledge base (auth required)
GET/api/public/brain/queryPublic query (no auth)
GET/api/tagsList all tags
POST/api/uploadUpload file (auth required)

Second Brain — Built with Next.js, Prisma, and AI