Engineering Decision Journal
A structured tool for documenting architectural decisions, tracking their evolution, and preserving the context future engineers need most.
Next.js App Router · React Server Components · TypeScript · Tailwind CSS
Context
Architectural decisions are made constantly, but often not documented adequately. When they are written down, it's usually in a Notion page that nobody can find, a Slack thread that's since been archived, or a GitHub PR comment with no broader context. Six months later, a new engineer makes the same decision, encounters the same constraints, and arrives at a worse answer because the thinking was never preserved.
Architectural Decision Records (ADRs) are a well-established practice for solving this. This tool makes them structured, searchable, and alive — with status tracking that reflects how decisions evolve: proposed, accepted, deprecated, superseded.
Anatomy of an ADR
Decision States
PROPOSED
Decision is drafted, under discussion
ACCEPTED
Ratified by the team, currently in effect
DEPRECATED
Still in place but being phased out
SUPERSEDED
Replaced by a newer decision (linked)
PROPOSED
Decision is drafted, under discussion
ACCEPTED
Ratified by the team, currently in effect
DEPRECATED
Still in place but being phased out
SUPERSEDED
Replaced by a newer decision (linked)
Explore the Journal
Below is a working decision journal. Read existing entries, change their status, or add your own.
Adopt Next.js App Router as the default rendering strategy
2024-03-12
Use Vercel Middleware for A/B test traffic splitting
2024-05-01
Postgres over a document store for experiment result storage
2024-05-15
Replace custom design system with Tailwind CSS v4
2024-08-20
Adopt Next.js App Router as the default rendering strategy
Context
The team was building a new customer-facing dashboard. We needed a rendering strategy that balanced SEO requirements, personalization, and performance at scale.
Constraints
Must support incremental migration from Pages Router. Team familiarity with React is high; familiarity with RSC is mixed. Launch deadline in 10 weeks.
Alternatives
Pages Router with getServerSideProps — familiar but increasingly legacy. Pure client-side SPA — ruled out due to SEO requirements. Remix — seriously considered, but Vercel-native tooling and team familiarity tipped the decision.
Decision
Adopt App Router. Begin with new routes only; migrate existing pages incrementally over Q2. Invest in RSC education in the first two sprints.
Outcome
Migration completed in 8 weeks. Core Web Vitals improved across all routes. RSC reduced client bundle size by ~40% on data-heavy pages.
Reflections
The most important design decision in this tool was making status a first-class concept rather than a freeform tag. Proposed, Accepted, Deprecated, and Superseded statuses map to the actual lifecycle of an architectural decision. The nuance between Deprecated and Superseded matters: one is fading out by choice, the other was explicitly replaced. Getting that taxonomy right makes the journal useful as an audit trail, and that's the distinction between this and your run-of-the-mill documentation.
In a production version, decisions would be stored in Postgres with a full revision history— every status change and edit recorded with a timestamp and author. The timeline view would reflect not just the current state but the full arc of how a decision evolved. Superseded decisions would link bidirectionally to their successors.
This is the kind of tooling that compounds in value over time. The tenth decision logged is useful. The hundredth is institutional memory. The thousandth is a competitive advantage: a team that can trace the reasoning behind every major architectural choice moves fundamentally differently than one that can't.