Cognis - Meeting Intelligence

A single-user, PM-focused meeting intelligence app.

Paste a meeting transcript and Cognis extracts the decisions and commitments buried in it, tracks them across meetings, and proposes when an older item looks finished or connected to a newer one — but never changes state without your explicit review.

Trust before automation. No auto-save, no auto-close.

---

📑 Table of Contents

• Why this exists
• What it does
• Key design decisions
• Architecture
• Tech stack
• Getting started
• Model connections
• Testing
• Security model
• Privacy
• Deployment
• Documentation
• License

---

💡 Why this exists

Meeting notes record intent, then lose it. Actions, owners, and due dates live in unstructured text and quietly fall out of attention. Existing note systems are good at retrieval and manual task extraction, but they don't reason across meetings to tell you that a specific commitment from three weeks ago is now done.

Cognis is built for that missing behavior:

• Extract commitments and decisions from each meeting
• Compare them against prior open items
• Propose likely closure and cross-meeting links
• Keep a human in the loop before anything is written

The design stance is deliberate: conservative extraction, evidence-backed suggestions, review before write, and the backend owns canonical state.

---

✨ What it does

Stage	What happens
📥 Paste	Submit a raw transcript for AI processing.
🧾 Review	Inspect proposed insights — new commitments, status changes, connections — before they save.
📊 Track	Manage commitments and the decisions linked to them.
🧠 Cognis Brain	A graph view of meetings and the relationships between them (continues_discussion, contradicts, blocked_by, resolves, mentions).

Commitments carry a status of OPEN, PARTIAL, CLOSED, or CANCELLED. Classification is conservative: CLOSED requires the owner to state completion explicitly about the same artifact, and a facilitator's end-of-meeting recap never counts as status evidence for that facilitator's own items.

---

🎯 Key design decisions

Decision	Rationale
Manual input only	Transcript paste for v1. Slack/Calendar/webhook integrations are deferred.
Review before save	All extracted items and suggestions are reviewed on screen before persistence. No silent writes from the model.
Closure is proposal-only	A new transcript can suggest closure; you confirm, keep open, or mark partial manually.
Owner matching is explicit	User identity = name + aliases. Unclear owners become Unassigned with needs_review=true.
Meeting timestamp required	Date + time + timezone — not date-only. Needed for correct chronological sequencing.
Every meeting is a graph node	No hidden meetings, even when disconnected.
Backend owns canonical state	Model output is proposal-only. The backend reconciles and guards against malformed output.
Privacy & retention upfront	Retention, export, and delete are first-class. Users are warned about third-party LLM handling of pasted data.

---

🏗️ Architecture

┌──────────────┐     ┌──────────────────────────┐
│  Frontend    │────▶│   Express API Server     │
│  (Vite SPA)  │     │   (Node.js + esbuild)    │
│  React + TS  │     │                          │
└──────────────┘     │   /api/healthz           │
       ▲             │   /api/* routes          │
       │             │   serves static frontend │
┌──────┴───────┐     │                          │
│ PostgreSQL   │◀────│   Drizzle ORM            │
│              │     │   OpenAI-compatible      │
└──────────────┘     │   AI integration         │
                     └──────────────────────────┘

A pnpm workspace with three parts:

Path	Purpose
artifacts/cognis	React + Vite frontend (Tailwind, Radix UI, TanStack Query)
artifacts/api-server	Express API, Drizzle ORM, AI processing pipeline
lib/	Shared packages: DB schema, generated API clients, Zod validators, AI integrations

---

🛠️ Tech stack

Layer	Technology
Frontend	React 19, Vite 7, TypeScript 5.9, Tailwind CSS 4, Radix UI, TanStack Query, wouter, Recharts
Backend	Node.js 20+, Express 5, Zod, Pino, esbuild
Database	PostgreSQL 16, Drizzle ORM (SQL + snapshots)
AI	OpenAI-compatible API (OpenAI, Anthropic, Gemini, or any custom endpoint)
API contract	OpenAPI 3 spec → Orval-generated client + Zod schemas (single source of truth)
Tooling	pnpm workspaces, Playwright (E2E), node:test (unit), GitHub Actions

---

🚀 Getting started

Prerequisites: Node.js >= 20, pnpm >= 9, and a PostgreSQL database (Supabase, Neon, RDS, or local).

git clone https://github.com/StuTashI/Cognis.git
cd Cognis
pnpm install

Set up the API server environment:

cp artifacts/api-server/.env.example artifacts/api-server/.env

Fill in DATABASE_URL and generate a session secret:

openssl rand -base64 32

Then push the schema and run it:

pnpm --filter db push
pnpm --filter @workspace/api-server run dev

The frontend dev server runs on :5173 and proxies /api to the API on :3457.

To produce a production frontend build, PORT and BASE_PATH must be set — the Vite config reads both and exits if they're missing:

cd artifacts/cognis && PORT=5173 BASE_PATH=/ pnpm run build

For containerized setup, docker-compose.yml brings up Postgres and the app together:

docker compose up --build

---

🔌 Model connections

Cognis is not tied to one AI provider. Add an OpenAI-compatible endpoint in Settings → AI Model Connections to use your own model. API keys are encrypted at rest (AES-256-GCM) and are never returned by the API or included in exports.

Meeting processing stays disabled until you add and activate a connection.

---

🧪 Testing

pnpm run typecheck            # TypeScript across the workspace
pnpm run test:date-utils      # date/timezone unit tests

The artifacts/cognis/e2e directory holds Playwright specs covering the dashboard, review queue, model connections, meeting deletion and retention, and timezone regressions.

pnpm --filter @workspace/cognis run test:e2e

---

🔒 Security model

Cognis is a single-user app and ships with no built-in authentication. Anyone who can reach the server port can read and modify data. If you deploy it to a public host, add your own auth layer (session, reverse-proxy auth, or a fronting gateway) in front of the API.

What the application does handle securely:

• Credentials at rest — model API keys are encrypted with AES-256-GCM and never leave the server.
• SSRF protection — model connections are validated against private/internal IP ranges; only public HTTPS endpoints are allowed in production.
• Input validation — every route validates its payload against Zod schemas before touching the database.
• Scoped queries — all reads and writes are scoped to the current user's meetings and commitments.
• Log hygiene — authorization headers, cookies, and query strings are redacted from logs.
• No secrets in the repo — .env files are git-ignored; only .env.example placeholders are committed.

---

🔐 Privacy

Raw transcripts and derived records default to a 90-day retention window, after which expired meeting data is removed. You can delete an individual meeting and its related records from its detail page.

---

🚢 Deployment

See DEPLOYMENT.md for the production guide, including Docker, nginx, and managed-Postgres options.

---

📚 Documentation

• COGNIS_SINGLE_PRODUCT_DOCUMENT.md — full product spec and decision log
• DEPLOYMENT.md — production deployment
• lib/api-spec/openapi.yaml — OpenAPI 3 contract for every endpoint

---

📄 License

Released under the MIT License.

---

Made with ☕ by StuTashI