TraceRoom
Incident investigation with a shared record of evidence, reasoning, and response.
TraceRoom is a local full-stack incident investigation MVP in active development. Its primary incident, investigation, collaboration, authorization, post-mortem, and audit workflows are implemented, while presence behavior, global search, production artifact storage, invitation delivery, and deployment hardening remain ongoing.
- Role
- Product design and full-stack engineering
- Scope
- Incident workflows, domain modeling, collaboration, authorization, persistence, auditability, post-mortem tooling, and product interface
- Status
- Local full-stack MVP · Active development
- Core stack
- React · TypeScript · NestJS · MongoDB
Product interface
A shared investigation room
TraceRoom connects chronological events, technical evidence, competing hypotheses, assigned work, mitigation decisions, discussions, resolution context, and post-mortem documentation in one persisted product. The case-study incident is a fully persisted seeded development scenario rendered through TraceRoom's normal schemas, API routes, membership checks, authorization rules, relationships, and real-time product workflows.
Product overview
Why this product exists.
Incident response produces more than a final resolution. Teams collect evidence, propose and reject hypotheses, assign investigation work, make mitigation decisions, discuss findings, and later reconstruct what happened. These records are often fragmented across chat, tickets, dashboards, and documents.
TraceRoom keeps those activities connected inside one incident workspace. The timeline, evidence, hypotheses, tasks, decisions, discussions, technical artifacts, and resolution record remain part of the same persisted investigation rather than separate pieces of context.
The local full-stack MVP uses a React and TypeScript frontend, a NestJS API, MongoDB persistence, role-aware authorization, real-time collaboration, structured post-mortems, notifications, audit history, Docker-based local development, and automated frontend, backend, API, and browser testing. The product remains in active development, with broader search, production storage, invitation delivery, presence behavior, and deployment hardening still in progress.
Problem / motivation
An incident record should explain not only what failed, but what the team observed, believed, rejected, investigated, decided, and changed while restoring the system.
Product experience
Key features.
- 01
Incident command and discovery
Surfaces active incidents, severity, ownership, affected services, unresolved work, and recent activity across the workspace.
- 02
Persisted investigation timeline
Preserves chronological observations, status changes, evidence, discussions, and incident lifecycle events as part of one durable investigation record.
- 03
Connected investigation reasoning
Links technical evidence to competing hypotheses, investigation tasks, mitigation decisions, and targeted discussions.
- 04
Structured response coordination
Tracks investigation work, ownership, priority, status, and mitigation decisions without separating them from the incident context that produced them.
- 05
Resolution and post-mortem workflow
Turns the persisted incident record into an editable post-mortem with structured resolution context and Markdown export.
- 06
Role-aware collaboration and auditability
Applies backend-enforced workspace permissions while preserving authorship, notifications, activity history, and audit context.
Under the surface
Architecture and technical challenges.
Architecture
- React and TypeScript client built with Vite, route-level product surfaces, shared contracts, and TanStack Query for server state
- NestJS domain modules with MongoDB and Mongoose persistence for workspaces, incidents, investigation records, collaboration, and post-mortems
- JWT authentication with short-lived access tokens, rotating HTTP-only refresh sessions, and backend-enforced workspace roles
- Socket.IO entity updates for live collaboration while transient presence remains separate from persisted incident truth
- Protected local artifact storage behind a replaceable service, Docker Compose, and automated frontend, backend, API, and Playwright testing
Challenges
- Modeling an incident as connected investigative reasoning rather than a collection of isolated notes
- Preserving chronological truth while allowing structured relationships between investigation records
- Enforcing active workspace membership and role permissions at backend mutation boundaries
- Synchronizing entity updates without treating transient participant presence as persisted truth
- Preserving authorship, notifications, audit context, and structured post-mortem output across the investigation lifecycle
Technology stack
Delivery status
What exists today.
Implemented
- Command Center, incident register, Investigation Room, and persisted incident timeline
- Linked evidence, hypotheses, tasks, decisions, discussions, and protected technical artifacts
- Structured resolution, editable post-mortems, Markdown export, notifications, activity, and audit history
- Workspace membership, backend-enforced roles, invitation links, and Socket.IO entity updates
- Docker Compose plus frontend, backend, API, and Playwright browser tests
Partial
- Search opens a scoped incident view rather than a complete cross-collection index
- Invitation workflows create local or copyable links; production email delivery is not connected
- Artifacts use access-controlled local filesystem storage behind a replaceable service
- Some edits, notifications, responsive behavior, accessibility, and production hardening remain active work
Experimental
- Transient Socket.IO participant-join presence; it is not persisted as incident truth
Planned
- Production object storage
- Email-backed invitation delivery
- Cross-collection global search
- Expanded workflow, integration, accessibility, responsive, and browser-test coverage
- Deployment, monitoring, secrets, and operational hardening
Interface
A closer look.
Surface 01
Incident command and discovery
The Command Center and incident register provide a workspace-level view of active incidents, severity, ownership, affected systems, unresolved work, and recent investigation activity before the user enters a specific room.
Command Center
Incident register
Surface 02
A shared investigation room
The Investigation Room keeps the incident timeline and active reasoning in one shared workspace. Evidence, hypotheses, assigned work, mitigation decisions, and discussions remain connected to the same persisted incident context.
Surface 03
Evidence and connected reasoning
Evidence does not exist as an isolated attachment. TraceRoom connects observations and technical artifacts to the hypotheses they support or challenge, the work they trigger, and the decisions that follow.
Surface 04
Resolution, post-mortem, and accountability
The investigation record continues into resolution and review. Structured post-mortems, activity history, notifications, authorship, and role-aware access preserve how the incident was handled rather than reducing it to a final status change.
Post-mortem editor
Security and audit history
Honest edges
Limitations and what comes next.
Current scope
- TraceRoom is a local full-stack MVP in active development.
- Presence remains experimental and is not used as persisted incident truth.
- Invitations use copyable links, artifacts use local storage behind an abstraction, and search remains incident-scoped rather than globally indexed.
- Production deployment, monitoring, infrastructure hardening, customer usage, and measured incident outcomes are not claimed.
Future improvements
- Introduce production-ready artifact and object storage.
- Add email-backed workspace invitation delivery.
- Expand global search across incidents and investigation entities.
- Continue presence, notification, collaboration, accessibility, responsive, and test-coverage refinements.
- Define hosting, secrets, storage, database, monitoring, and operational requirements before deployment.