Second Brain: Architecture & Design
Comprehensive documentation on system architecture, design principles, and infrastructure. Built for portability, performance, and maintainability.
Quick Facts
- Tech Stack: Next.js 16 + React 19 + Prisma + PostgreSQL + Groq
- Database: PostgreSQL with Prisma ORM (supports Neon, Supabase, local)
- AI Model: Groq LLama 3.1 8B (fast, free tier available)
- Deployment: Vercel, Netlify, or any Node.js host
- Status: Production-ready, includes error handling and fallbacks
Design Principles
Portable Architecture
Presentation (App Router + components), domain/service layer (`src/lib`), and data access (`Prisma`) are separated so providers can be swapped independently. Switch databases without touching UI. Replace Groq with OpenAI by editing one file.
UX Principles
Optimized for clarity, speed, and composability: high signal hierarchy (list → detail → full), low-friction forms, deterministic filtering, and mobile-responsive design. Users can capture and search knowledge in seconds.
Agent Thinking
On ingestion, items are enriched by AI (summary + tags) or deterministic fallback if API unavailable. Query flow uses relevance ranking before synthesis for source-grounded answers. Keeps knowledge flow explicit and cacheable.
Infrastructure Mindset
Capabilities exposed through public API route `GET /api/public/brain/query` suitable for widgets or external integrations. Stateless design runs on Vercel, Netlify, or AWS Lambda. Cold-start optimized with minimal dependencies.
Layered Architecture
Clear separation of concerns enables swappable providers and independent testing:
| Layer | Location | Responsibility |
|---|---|---|
| Presentation | src/app/*, src/components/ | React components, page routing, client-side state |
| API Interface | src/app/api/ | HTTP routes, request validation (Zod), response formatting |
| Service Layer | src/lib/knowledge-service.ts | Business logic (CRUD, retrieval, ranking) |
| AI Adapter | src/lib/ai.ts | LLM calls (Groq), summarization, tagging, synthesis |
| Validation | src/lib/knowledge-schema.ts | Input/output schema validation (Zod) |
| Data Access | prisma/ | Database schema, migrations, ORM queries |
Data Flow
1. Capture
User submits form → POST /api/knowledge → validation (Zod)
2. Enrich
knowledge-service calls ai.ts → Groq API → summary + tags (or fallback)
3. Store
Prisma ORM → PostgreSQL (create record + tags)
4. Query
GET /api/knowledge?q=... → filter/sort → return to UI
5. Synthesize
GET /api/public/brain/query → rank sources → LLM synthesis → public response
API Endpoints
All routes are type-safe and return validated responses:
| Method | Path | Query/Body | Description |
|---|---|---|---|
| GET | /api/knowledge | q, type, tag, sort | List knowledge items |
| POST | /api/knowledge | title, content, type | Create item + enrich with AI |
| GET | /api/knowledge/:id | — | Get single item |
| GET | /api/public/brain/query | question | Query endpoint (public API) |
Technology Rationale
Why these tools were chosen:
Next.js 16
Full-stack JS, API routes, optimized builds, serverless-ready
React 19
Modern hooks, better performance, concurrent features
Prisma
Type-safe DB access, automatic migrations, relation querying
PostgreSQL
Reliable, JSONB for array fields, full-text search support
Zod
Runtime validation on boundaries, type inference, clear errors
Groq
Fast inference, free tier, OpenAI-compatible API
Tailwind v4
Utility-first, responsive, no CSS compilation overhead
Swappable Components
Change Database Provider
Edit `prisma/schema.prisma` datasource, update `.env` connection URL, run `npm run db:push`. UI and API remain unchanged.
Change AI Provider
Replace Groq calls in `src/lib/ai.ts`. Update `.env` credentials. Service layer interface stays the same.
Change UI Framework
Rebuild `src/app/*` and `src/components/*` in Vue/Svelte/etc. API and service layer are language-agnostic.
Deployment Checklist
- ✓ Database provisioned (Neon, Supabase, or self-hosted PostgreSQL)
- ✓ Schema pushed: `npm run db:push`
- ✓ `.env` variables set locally and in production
- ✓ Groq API key obtained (or app works without it with fallback)
- ✓ Code pushed to GitHub
- ✓ Vercel/Netlify connected and environment variables set
- ✓ Build succeeds and app loads at production URL
Questions?
See the dashboard for a live demo, or check GitHub repo for source code.