A record of significant product, technical, and business decisions. Documenting decisions helps future team members understand why things are the way they are.
How to Use This Log
When making a decision that affects the product direction, architecture, or business strategy, add an entry below. Include:
- What was decided
- Why (the rationale)
- What alternatives were considered
- Who was involved
Decisions
2026-02 — Use Docusaurus for knowledge base
| Field | Detail |
|---|
| Decision | Use Docusaurus (not Notion, GitBook, or a custom site) for the product knowledge base |
| Rationale | Markdown-based content is easy for non-technical users to edit. Built-in Mermaid support renders architecture diagrams without external tools. Deploys to Vercel like the main app. |
| Alternatives | Notion (collaborative but less control over presentation), GitBook (nice but paid tier for custom domains), custom Next.js site (more work to maintain) |
| Status | Implemented |
2026-01 — Use Claude 3.5 Haiku for all AI functions
| Field | Detail |
|---|
| Decision | Use Claude 3.5 Haiku (claude-3-5-haiku-20241022) for all 12 AI functions |
| Rationale | Haiku provides fast response times critical for real-time conversations. Cost-efficient for high-volume analysis. Quality is sufficient for follow-up generation and theme extraction. |
| Alternatives | Claude Sonnet (higher quality but slower and more expensive, considered for analysis-only), GPT-4 (different API ecosystem), mixed models (complexity of managing multiple providers) |
| Status | Active |
2025 — Token-based participant access
| Field | Detail |
|---|
| Decision | Participants access conversations via a unique UUID token in the URL — no login required |
| Rationale | Minimizes friction for participants. They receive an email, click a link, and start chatting. No password to remember, no account to create. |
| Alternatives | Email magic links (still requires a click-through auth step), embedded auth (too heavy for one-off respondents) |
| Status | Active |
2025 — Supabase for database and auth
| Field | Detail |
|---|
| Decision | Use Supabase (hosted PostgreSQL) for database, authentication, and row-level security |
| Rationale | Provides auth, database, and RLS in one service. Generous free tier for early stage. JWT-based auth integrates cleanly with Express backend. |
| Alternatives | Firebase (NoSQL doesn't fit relational data model), Auth0 + raw PostgreSQL (more services to manage), Prisma + PlanetScale (good but Supabase is more integrated) |
| Status | Active |
2025 — Separate frontend and backend deployment
| Field | Detail |
|---|
| Decision | Deploy frontend to Vercel and backend to Render as separate services |
| Rationale | Vercel excels at static/SPA hosting with global CDN. Render handles the Node.js backend with easy environment variable management. Separation allows independent scaling. |
| Alternatives | Monolith on Render (simpler but no CDN for frontend), Vercel serverless functions (cold start concerns for real-time AI conversations), Railway (good alternative, kept as backup) |
| Status | Active |
Add new decisions above this line, with the most recent first.