Architecture

3ngram system architecture overview. FastAPI backend, MCP server, Next.js frontend, PostgreSQL with pgvector, and the principles that guide development.

System overview

3ngram consists of three services sharing a single PostgreSQL database:

Frontend (Next.js 16)         Web UI for dashboard, documents, search
        │ REST API
        ▼
Backend (FastAPI)             Routers > Services > Database (psycopg3 async)
        │ shared DB only
MCP Server (FastMCP)          16 tools + 3 prompts (psycopg3 sync)
        │
        ▼
PostgreSQL 16 + pgvector      documents, memories, content_chunks, clusters

The web frontend is the human interface. The MCP server is the AI interface. They share the database but never import from each other.

Tech stack

Layer	Technology
Frontend	Next.js 16, React 19, TanStack Query, Tiptap/Novel editor
API	FastAPI, psycopg3 (async), Pydantic v2
MCP	FastMCP, psycopg3 (sync, ConnectionPool), Streamable HTTP
Database	PostgreSQL 16, pgvector, Alembic migrations
Embeddings	OpenAI text-embedding-3-small (1536-dim)
Auth	JWT (API), OAuth 2.0 (MCP)
CI	GitHub Actions (ruff, mypy, pytest, Playwright, Bandit)

Core principles

1. MCP-first: AI tools are the primary interface; the web app is for overview and data portability
2. Structured memories: Commitments, decisions, blockers, and context have lifecycle semantics
3. User isolation is mandatory: All queries filter by user_id. RLS policies enforce this at the database layer
4. Module isolation: engram.mcp and engram.api never import each other
5. Services own business logic: Routers handle HTTP concerns only
6. Self-contained memories: Every memory makes sense in isolation, months later
7. Auth can be disabled: AUTH_ENABLED=false for local single-user mode
8. LLM consent is opt-in: Memory consolidation via external LLM defaults to off

Data model

3ngram stores three types of data:

Store	Table	Description
Documents	documents	Tiptap JSON. User notes edited through the web UI. Never split into chunks.
Memories	memories	Structured recall. 6 types: decision, commitment, blocker, preference, pattern, context.
Content chunks	content_chunks	Indexed markdown with 1536-dim embeddings. Derived index, rebuildable.

Deployment

Service	Platform	Trigger
Backend (API + MCP)	Railway	Auto-deploy on merge to main/staging
Frontend	Vercel	Auto-deploy on merge to main/staging
Database	Railway (PostgreSQL)	Managed

Self-hosted deployments use Docker Compose with four containers. See Self-Hosting.