This repo includes a minimal end-to-end slice to ingest a single Markdown document via API, persist it, and view it on the client. Images are intentionally omitted for now.
- Minimal Prisma model
Docwithtitle,markdown,html, timestamps - API routes to ingest and fetch a document
- Home page with a simple ingest form that navigates to the document viewer
- Viewer page that renders the stored HTML
- Vitest integration test that mocks Prisma and exercises ingest + fetch
- Node.js 24+ and pnpm 9.15.9 (pinned in
app/package.json; runcorepack enableor prefix commands withcorepack) - Homebrew. Dev and tests use Homebrew Postgres, not Docker; see app/docs/local-postgres.md
cd app
pnpm install
pnpm prisma generatepnpm audit:db -- --owner <slug>This starts Homebrew Postgres if it is not running, creates visual_notes_audit_<slug>, applies the migrations, and prints the command that starts the app on it. See app/docs/local-postgres.md to reset a database or copy data from the old Docker container.
pnpm devThe app runs at http://localhost:3000.
Notes are created and edited in the app, by in-app AI, and by the ChatGPT MCP connector. Bulk ingest (the old cli-ingest tool and its sync endpoints) has been removed.
POST /api/docs creates one note for a signed-in client (the e2e fixtures use it):
{ "title": "My Doc", "markdown": "# Hello\nSome text." }It returns { "id": "..." } with status 201.
Open tabs refresh when notes change elsewhere (ChatGPT, other tabs, the CLI). See app/docs/live-note-updates.md. A reverse proxy must forward WebSocket upgrades for /ws/notes.
Collections are typed sets of notes, like Notion databases. Each row is an ordinary note, so search, links, revisions, and the ChatGPT connector all work on rows. The collection adds a property schema on top.
- Pages:
/collectionslists them, and/collections/:idshows saved views as tabs. - Views:
- Table: inline editing, filters, sorts, footer summaries, bulk edit, and windowed rows.
- Board: grouped by a select or status property; drag cards to change the value.
- Gallery: cards with a cover image and a body preview.
- Calendar: a month grid by a date property; drag to reschedule.
- Property kinds: text (formats: plain, URL, email, phone), number (formats: plain, decimal, percent, currency, rating, progress), select, status (options grouped into To do, In progress, and Done), multi-select, date (with optional end date and time), checkbox, and created or updated time.
- In notes: type
/collectionto embed a live, editable view. A row's note page shows its properties and a link back to its collection. - Existing notes: use "Add notes" on a collection page, or "Add to collection…" in a note's ⋯ menu. Meta keys that match property names fill those properties.
- Storage: values live on
Doc.properties, keyed by property id; the row's body is the note's block content (Doc.content). Views and their filters live inCollectionView. The embed is thecollectionViewnode in the shared note schema, and gallery covers and previews read bodies through the note store (services/collections/note-summary.ts). Rules and decisions are in app/docs/collections.md. - Local fixtures: run
cd app && node --experimental-strip-types --env-file=.env scripts/seed-collections.tsagainst an audit database (visual_notes_audit_*only), then runpnpm migrate:blocks --applyto give the seeded rows block bodies.
cd app
pnpm testCompose is for production deploys. Dev work does not need Docker.
A minimal Compose setup lives in app/docker-compose.yml and runs Postgres + the app. No external APIs are required for the minimal Markdown ingest flow.
cd app && docker compose up --buildThen open http://localhost:3000.
Codex reads repo-local MCP server settings from /Users/byronwall/Projects/visual-notes/.codex/config.toml.
This repo keeps Playwright on --isolated there so Codex sessions do not reuse a shared browser profile.
- Starts Postgres (
db) with default credentials and databasevisual_notes. - Builds the app image, then runs it on port 3000.
- On container start, the app runs
prisma migrate deployautomatically. GET /api/version(no sign-in) returns the deployedcommitand serverstartedAt. The server readsSOURCE_COMMITat runtime. Coolify writes it to the.envfile it adds to each compose service, so the build cache stays valid. Do not reference${SOURCE_COMMIT}indocker-compose.ymlor add it as a Coolify env var: either one makes an app env var that hides the real value. Run by hand, the commit isunknown.- Before serving requests, it fills missing
Doc.searchTextvalues in batches. This preserves note edit dates. - Content writes keep plain search text current. PostgreSQL uses a
pg_trgmindex for substring matches.
In case you need to override ports or database settings:
# App port mapping (host:container)
APP_HOST_PORT=3000 \
# DB settings used by Compose and to construct DATABASE_URL
DB_USER=postgres \
DB_PASSWORD=postgres \
DB_NAME=visual_notes \
DB_HOST_PORT=5432 \
docker compose up --buildInside the app container, DATABASE_URL is set to postgresql://postgres:postgres@db:5432/visual_notes?schema=public by default.
This app now supports computing OpenAI embeddings for each stored document and generating UMAP projections for visualization. The client canvas at /visual will automatically use the latest UMAP run to position notes (falls back to a seeded layout if no run exists).
/embeddings— Create a new embedding run and view recent runs/embeddings/[id]— View a run, delete it, and trigger a UMAP run (2D/3D)/umap— Create a UMAP run for a selected embedding run and view recent runs/umap/[id]— View a UMAP run, delete it, and preview the first 48 points/visual— Canvas visualization; uses the latest UMAP run if present
Set these in your shell or via Compose (see below):
OPENAI_API_KEY: Required to call OpenAI embeddings APIEMBEDDING_MODEL: Model id (defaulttext-embedding-3-small)UMAP_PYTHON_BIN: Python executable for persisted UMAP (defaultpython3)UMAP_MODEL_DIR: Directory for saved UMAP artifacts (default/app/data/umap-modelsin Docker)
The Compose file passes through OPENAI_API_KEY, sets a default for EMBEDDING_MODEL, and configures UMAP_PYTHON_BIN/UMAP_MODEL_DIR.
For local (non-Docker) runs, install Python deps once:
cd app
pnpm umap:setup:localEmbeddingRun(id, model, dims, params, createdAt)DocEmbedding(id, runId, docId, vector Float[], createdAt)UmapRun(id, embeddingRunId, dims, params, artifactPath?, createdAt)UmapPoint(id, runId, docId, x, y, z?)
Embeddings are stored as Float[] for simplicity (no pgvector required). UMAP points are stored per-run so multiple runs can coexist. Persisted UMAP artifacts (joblib) allow reusing trained models for fast future transform calls.
- Train (
createUmapRun): fit Pythonumap-learn, persist artifact, write initial points. - Project (
projectUmapRun): load artifact, transform fresh embeddings, upsert points without retraining. processEmbeddingRunnow auto-projects newly embedded docs into trained UMAP runs for that embedding run, so fresh notes can appear immediately on the canvas.
-
POST /api/embeddings/runs→ Computes embeddings for all docs and creates a newEmbeddingRun.- Body (optional):
{ "model": "text-embedding-3-small" } - Response:
{ runId, count }
- Body (optional):
-
GET /api/embeddings/runs→ Lists recent embedding runs -
GET /api/embeddings/runs/[id]→ Returns a single run with{ id, model, dims, params, createdAt, count } -
PATCH /api/embeddings/runs/[id]→ Updatemodel,dims, orparamsmetadata -
DELETE /api/embeddings/runs/[id]→ Deletes the run and itsDocEmbeddingrows -
POST /api/umap/runs→ Creates a UMAP projection for a given embedding run- Body:
{ "embeddingRunId": string, "dims": 2 | 3, "params"?: { "nNeighbors"?: number, "minDist"?: number, "metric"?: "cosine" | "euclidean" } } - Response:
{ jobId: null, runId }
- Body:
-
GET /api/umap/runs→ Lists recent UMAP runs -
GET /api/umap/runs/[id]→ Returns a single run with{ id, dims, params, embeddingRunId, createdAt, count } -
PATCH /api/umap/runs/[id]→ Updatedimsorparamsmetadata -
DELETE /api/umap/runs/[id]→ Deletes the run and itsUmapPointrows -
GET /api/umap/points?runId=...→ Returns{ runId, dims, points: [{ docId, x, y, z? }], meta: { count } }
- Ingest a few docs (see earlier examples), then compute embeddings:
curl -s -X POST http://localhost:3000/api/embeddings/runs \
-H 'Content-Type: application/json' \
-d '{"model":"text-embedding-3-small"}' | jq .- List embedding runs and pick one:
curl -s http://localhost:3000/api/embeddings/runs | jq .- Create a UMAP run from that embedding run:
EMB_RUN_ID="<paste-from-step-2>"
curl -s -X POST http://localhost:3000/api/umap/runs \
-H 'Content-Type: application/json' \
-d "{\"embeddingRunId\":\"$EMB_RUN_ID\",\"dims\":2,\"params\":{\"nNeighbors\":15,\"minDist\":0.1,\"metric\":\"cosine\"}}" | jq .- Open the canvas at
http://localhost:3000/visual. The latest UMAP run is fetched automatically to position notes.
Embedding run detail:
curl -s http://localhost:3000/api/embeddings/runs/<runId> | jq .Update embedding run metadata:
curl -s -X PATCH http://localhost:3000/api/embeddings/runs/<runId> \
-H 'Content-Type: application/json' \
-d '{"params":{"note":"my tag"}}' | jq .Delete embedding run (also removes vectors):
curl -s -X DELETE http://localhost:3000/api/embeddings/runs/<runId> | jq .UMAP run detail:
curl -s http://localhost:3000/api/umap/runs/<runId> | jq .Delete UMAP run (also removes points):
curl -s -X DELETE http://localhost:3000/api/umap/runs/<runId> | jq .Pass your OpenAI key when starting Compose:
cd app
OPENAI_API_KEY=sk-... EMBEDDING_MODEL=text-embedding-3-small \
docker compose up --buildThe app/docker-compose.yml forwards OPENAI_API_KEY and sets a default EMBEDDING_MODEL. On container start, Prisma migrations are applied before serving.
