TraceVault
Knowledge platform for engineering experience: write up bugs, trade-offs and design calls, then search, share, save and discuss them. Feed, vault, collections, live threads and email MFA.
Overview
A knowledge platform for engineering experience. You write up the bug, the trade-off or the design call while it is fresh, tag it, and it becomes searchable, shareable and discussable instead of being forgotten.
- Prisma models
- 13
- Migrations
- 15
- Entry categories
- 7
- Stack
- NestJS + Next.js
It began as a project-scoped debug log (User → Projects → Entries) and grew into a small social product: a public feed, upvotes, a personal vault, collections, entry threads and public profiles with an activity heatmap.
The product
An entry is called a reflection. It has a category, an impact level and a visibility, so a quick note and a production-breaking postmortem do not look the same.
| Concept | Values / behaviour |
|---|---|
| Category | Design decision, technical challenge, trade-off, lesson learned, bug autopsy, integration note, social post |
| Impact | Minor, moderate, critical, breaking |
| Visibility | Public (shows in the feed) or private |
| Structured fields | A JSON "fields" column driven by per-category templates (template-definitions.ts), plus free-form content and tags |
| Vault | Save someone else's entry to your own vault (unique per user and entry) |
| Collections | Group entries into named collections and add from a popover anywhere in the app |
| Votes | Upvote / downvote, one per user per entry |
The original idea was a plain Problem / Error / Cause / Solution / Lesson record. Those became the structured fields of the bug-autopsy template, so the useful shape survived while other kinds of engineering writing got their own templates.
Data model
Postgres through Prisma, with the schema evolved by migration rather than rewritten.
User ─┬─ Project ──── Reflection ─┬─ Vote (unique entry + user)
│ └ ProjectMembers ├─ VaultEntry (unique user + entry)
│ (OWNER/CONTRIBUTOR ├─ CollectionEntry (unique collection + entry)
│ /VIEWER) └─ ReflectionThread ── ThreadMessage
├─ Collection
├─ TrustedDevice
└─ EmailOtps- Indexes · Reflection is indexed on (userId, occurredAt desc) and (projectId, occurredAt desc), which are the two queries every profile and project page makes.
- Optional project · projectId is nullable so a standalone post does not need a project. Deleting a project cascades to its entries.
- Teams · ProjectMembers carries a role, so a project can have owners, contributors and read-only viewers.
- Search readiness · An IndexState enum (unindexed → queued → processing → ready / failed) is in place for retrieval indexing.
Auth & security
Started as email + password with JWT and grew into a full account-security flow.
- Passwords · Hashed with bcrypt. Registration, login and reset use validated DTOs behind a global ValidationPipe.
- Sessions · JWT access tokens, with refresh-token fields added to the user by migration and cookie-parser enabled. An optional JWT guard lets public pages personalise for signed-in users without requiring a login.
- MFA · Email one-time codes (EmailOtps) with TrustedDevice records, so a device you have verified is not challenged every time. Has its own verify-mfa screen.
- Recovery · Forgot-password and reset-by-token flow, with the token fields added by migration and an email service that sends the message.
- CORS · An explicit origin allowlist with credentials enabled: localhost in development, the configured frontend URL in production.
Threads
Every entry can have a discussion thread that updates live.
- Transport · A socket.io gateway on the /threads namespace inside the NestJS app.
- Auth · The gateway authenticates the socket with the same JWT service as the REST API, so a message always carries a real author (id, username, avatar).
- Rooms · Each entry has at most one ReflectionThread, and messages are stored as ThreadMessage rows with an author, so history survives a reload.
Frontend
Next.js App Router with route groups, CSS modules and a set of focused components.
| Route | What it is |
|---|---|
| /feed | Public feed of entries with sort and filter |
| /projects, /projects/[id] | Your projects, with cards, sort/filter bar, empty states and collection rows |
| /reflections/[id] | Entry detail, edit page and live thread |
| /collections/[id] | A saved collection |
| /u/[username] | Public profile: identity header, activity heatmap, engineering breakdown, entry list |
| /settings | Profile, security (MFA) and history |
| (auth) | Register, login, MFA verify, forgot and reset password |
Delivery
Containerised backend, CI that proves the image boots, and a separately deployed frontend.
- Docker · Dockerfiles for backend and client, plus docker-compose files for local and production.
- CI · GitHub Actions builds the production compose stack, then polls the backend container until it reports running and fails the build with its logs if it does not. Pushes to non-main branches also run a preview deploy job.
- Hosting · Frontend on Vercel; the backend image is built for an EC2 host (the commit history is mostly Docker and CI tuning for it).
Deep dive
Bugs that cost real time, with what the symptom looked like, the actual cause, and the fix.
Context
The first model was strictly User → Project → Entry. Once people wanted to post without a project and read each other's work, that tree was the constraint.
Change
Made Reflection.projectId optional, added a SOCIAL_POST category, a visibility flag and the feed. Project-bound entries and standalone posts now live in one table instead of two.