Notion is a trademark of its respective owner. Noema is not affiliated with, endorsed by, or derived from Notion's source code, assets or trademarks. It implements the same category of product from publicly documented behaviour only. See Notice.

• Stack: Next.js 15 (App Router) · React 19 · TypeScript · Tailwind CSS v4 · Prisma 6 · PostgreSQL (docker container noema-db, port 5433) · TipTap · Tauri 2 for the desktop app
• Runs locally: one docker compose up for the database, one npm run dev for the app.
• Runs as an app: one installer — no Postgres, no Docker, no account. See Desktop app.
• License: MIT · Built by Bilel Guembri and Wissal Ben Othmen

---

Contents

Demo

▶ Watch the two-minute product film — one pass over every area: the block editor, seven database views, conditional formatting, tickets with labels and estimates, cycles and burndown, projects and milestones, the workspace roadmap, grounded chat, comments, version history, sharing and the desktop build.

The film is not a screen recording: every frame is composed from captured screenshots of the running app, so it is reproducible. The project lives in video/ — npm install && npm run render.

Status

This repository is a working application plus a complete parity tracker.

• The app runs and implements the core workspace loop (auth → workspaces → nested pages → block editor → databases → search → comments → history) and well beyond it: tickets, projects and cycles, workspace chat, AI, sharing and SSO, signed webhooks, and the desktop build.
• Every feature area is tracked in docs/FEATURE_MATRIX.md — 563 rows, each with a status and a note explaining the current state. Today: 454 implemented · 87 partial · 0 planned · 22 deliberately out of scope.
• Nothing is dropped silently. What is unfinished is enumerated in docs/MISSING_FEATURES.md, generated from the matrix by npm run docs:gaps, so the two cannot disagree.

Implemented today

Everything not yet implemented is enumerated in the feature matrix with a 🧭 Planned status.

Desktop app

The same codebase also builds into a per-user Windows installer: a Tauri 2 shell around a bundled Node runtime and an embedded PostgreSQL (PGlite). It needs nothing else on the machine — no Docker, no external database, no account.

Packaging, security posture and the install verification harness are documented in docs/DESKTOP.md.

Screenshots

Every screen is captured from the seeded demo workspace by scripts/screenshots.mjs — generated, not hand-taken, so a surface that changes takes its screenshot with it. The full set of 44, with captions, is in docs/GALLERY.md.

The same shots are laid out beside the feature list in docs/Noema-features.pdf — a printable feature sheet, built by npm run features:pdf from the README's own feature tables and the screenshot report, so the document cannot drift from the product either.

The landing page sits at the top of this file. The rest of the interface — search, databases, tickets, chat, the editor, sharing — is specified in docs/specs/ and tracked row by row in docs/FEATURE_MATRIX.md.

AI configuration

Any OpenAI-compatible provider works. Example (DeepSeek):

AI_API_KEY="sk-…"
AI_BASE_URL="https://api.deepseek.com"
AI_MODEL="deepseek-flash"

Transport is centralised in src/lib/ai-provider.ts (one place for base URL, model, timeouts and error mapping).

Troubleshooting

Clicks do nothing / “Saving…” never finishes / comments and chat appear dead. These are all Server Action failures — the UI can't tell you, it just waits. Two known causes:

1. Origin mismatch. Next.js only accepts a Server Action when the request's Origin matches the Host. If you reach the app through a hostname it doesn't know (a LAN IP after a rebuild, 127.0.0.1 vs localhost, or a reverse proxy/tunnel), every action is aborted. Noema allow-lists loopback, this machine's LAN addresses and the usual ports automatically; add anything else (proxy, tunnel) with APP_ORIGINS, then restart:

   APP_ORIGINS="noema.example.com,my-tunnel.ngrok.app"
   

2. Stale tab after a rebuild. A browser tab left open across npm run build still holds the previous build's action ids, so every action fails. Hard-reload (Ctrl+Shift+R) after a rebuild.

Diagnostics: npm run check:routes prints a Server Action origin matrix (same origin / loopback / LAN must pass, foreign origins must be rejected). Any residual failure now raises a toast (ActionErrorGuard) instead of hanging.

The editor's selection menus (colour, highlight, Ask AI). These render as a panel pinned under the toolbar, measured at click time — they used to be portalled popovers that lost their trigger and appeared in the top-left corner. Escape or a click elsewhere dismisses them.

Permissions: guests, teamspaces, page shares

Storage & backups

Cycles (sprints)

/w/<slug>/cycles turns estimates into a plan:

Collaboration depth

Search

Content search is Postgres full-text, not a JavaScript scan: every page keeps a plain-text mirror (Page.searchText) updated on write, indexed with a GIN index over to_tsvector('english', …). Queries use websearch_to_tsquery with ts_rank ordering, a to_tsquery prefix pass so typing "road" finds "roadmap", and ts_headline snippets. Trashed pages are excluded; pages whose mirror predates the feature fall back to a substring match. Run npm run setup:search after a fresh database (the index is an expression index, so it lives in SQL rather than in the Prisma schema)

Workspaces

Create, switch and administer workspaces without leaving the sidebar.

Tickets (issues)

/w/<slug>/tickets — a Linear-style tracker on top of the workspace:

Labels live at Settings → Ticket labels (create, rename, recolour, describe, delete with usage counts) and are shared by every ticket in the workspace. Use npm run seed:tickets to drop in a demo backlog, or Create ticket from page in the sidebar's right-click menu to turn a note into an issue.

AI conversations (chat)

The conversation opens as a docked panel in the main area (next to the note it is about) — the sidebar keeps the list and the panel is the conversation.

UI & design system

The interface follows the product it mirrors: a white canvas, a #f7f7f5 sidebar and 4–8px radii, driven by CSS custom properties in src/app/globals.css (--bg --sidebar --surface --fg --muted --accent, dark variants under .dark).

Remaining work is enumerated in docs/MISSING_FEATURES.md (generated from the feature matrix by npm run docs:gaps): of 563 tracked rows, 87 are still partial and 22 are deliberately out of scope — the rest are implemented — with a priority shortlist at the top.

LaTeX

Type $x^2$ for inline maths or $$…$$ for a block equation and it becomes a real, editable math node (live KaTeX preview dialog; click any equation to edit). Pasting text that contains formulas converts them too, and a "looks like maths" guard leaves prices ($5 and $6) alone.

Email, invitations & projects

AI provider (per workspace)

Settings → AI provider connects your own model. Keys are encrypted with AES-256-GCM (key derived from AUTH_SECRET) and are never sent back to the browser.

Pick a model from the curated list or press Fetch models to pull the provider's live GET /models, then Test connection before saving. Environment variables (AI_API_KEY / AI_BASE_URL / AI_MODEL) stay as the fallback for workspaces without their own configuration.

Enterprise & AI

Quick start

Requirements: Node.js 24 (the toolchain is typed against Node 24 — @types/node ^24), npm, Docker.

# 1. Database — Postgres 16 in the `noema-db` container, mapped to localhost:5433
docker compose up -d

# 2. Environment — required keys: DATABASE_URL (already points at :5433), AUTH_SECRET
cp .env.example .env        # then set a real AUTH_SECRET (see .env.example for the generator)

# 3. Install dependencies (postinstall runs `prisma generate`)
npm install

# 4. Create the schema, seed demo content, build the search index
npm run db:push
npm run db:seed
npm run setup:search        # optional: FTS GIN index + searchText backfill (safe to re-run)

# 5. Run
npm run dev                 # http://localhost:3000 (Next.js default port)

.env keys — everything is documented in .env.example:

Production: npm run build then npm start. Note that dev and prod share the same .next directory — never run them at the same time.

Docker image

A multi-arch (amd64 + arm64) image is published to the GitHub Container Registry on every main push and v* tag:

cp .env.example .env          # set a real AUTH_SECRET
docker compose --profile app pull app
docker compose --profile app up -d
# http://localhost:3202

It is a standalone, non-root image that runs migrations on start-up, ships a healthcheck, and is signed with cosign (keyless) with SBOM and provenance attestations. Full configuration, reverse-proxy notes, signature verification and the image tags are in docs/DOCKER.md.

Servers & ports

Playwright's default baseURL is http://localhost:3200 (see playwright.config.ts), so start the production server on :3200 before npm run e2e — or point the suite at any other server with E2E_BASE_URL (the dev server on :3201 is already running: E2E_BASE_URL=http://localhost:3201 npx playwright test).

Demo credentials

email:    [email protected]
password: password123

The demo account is created by the seed script. Change or remove it before any real deployment.

Scripts

Project layout

noema/
├─ prisma/
│  ├─ schema.prisma        # full domain model
│  └─ seed.ts              # demo workspace, database and rows
├─ src/
│  ├─ app/                 # routes: landing, auth, /w/[slug]/...
│  ├─ components/          # sidebar, editor, database views, comments, UI
│  ├─ lib/                 # auth, db, permissions, blocks, validation, utils
│  └─ server/
│     ├─ actions/          # server actions (auth, workspaces, pages, database, comments)
│     └─ queries.ts        # read model used by server components
├─ docs/
│  ├─ ARCHITECTURE.md
│  ├─ FEATURE_MATRIX.md    # Notion parity tracker (563 feature rows)
│  ├─ specs/               # design specs (saml-sso, relations-rollups, realtime-collab)
│  └─ ROADMAP.md
├─ scripts/
│  └─ check-*.mjs          # the check:* gates above
└─ docker-compose.yml

Architecture

See docs/ARCHITECTURE.md. Highlights:

• Everything is a page. Documents, folders and database rows are all Page rows; databases are pages of type DATABASE whose children are rows.
• Server-first. React Server Components read through src/server/queries.ts; mutations are Next.js server actions that re-check workspace access.
• Block documents. A page's blocks are a ProseMirror/TipTap JSON document in Page.content, with plaintext/Markdown helpers in src/lib/blocks.ts.
• Typed databases. Property + PropertyValue (JSON per type) + DatabaseView decouple the schema from the views (table/board/list/…).

Security

Found a vulnerability? Please do not open a public issue — follow SECURITY.md so it can be handled privately first.

• Passwords hashed with bcrypt (cost 12); sessions are HS256 JWTs in httpOnly cookies.
• Every server action re-derives workspace access from the session; guests are read-only.
• Set a strong AUTH_SECRET and use secure cookies + HTTPS in production.
• Share links are live: /s/<token> (optional password + expiry) and the single-use, hashed /invite/<token> invitation links — both re-check access on the server rather than trusting the URL.
• No credential belongs in the tree: npm run check:secrets fails on any committed key-shaped value, and .env is git-ignored.

Where to read next

Conversations are addressable: /w/<slug>?chat=<threadId> opens that discussion in the docked panel. Deleted pages live at /w/<slug>/trash (restore · delete forever · empty trash).

Notice

Noema is an independent project. "Notion" is a trademark of its respective owner and is referenced only descriptively for interoperability/education. No Notion source code, assets, copy or branding is included or redistributed.

Contributing

Contributions are welcome — bug reports, fixes, documentation and translations alike. Start with CONTRIBUTING.md for setup, the gate list and commit style, and read CODE_OF_CONDUCT.md before opening a pull request.

The honest list of what is missing lives in docs/MISSING_FEATURES.md — it is generated from the feature matrix, so it never drifts from reality. That is the best place to find something worth building.

Authors

Noema is built by:

• Bilel Guembri
• Wissal Ben Othmen

See AUTHORS.md for the full list, and CHANGELOG.md for what changed when.

License

MIT © 2026 Bilel Guembri, Wissal Ben Othmen.