| description | Document decisions and learnings from this session |
|---|
At the end of a session, preserve the knowledge gained by creating either an architectural decision record or a learning document.
- After fixing a bug (especially after multiple attempts)
- After implementing a new feature
- After making an architectural or design decision
- After discovering a non-obvious solution
- When something felt "magical" and you want to demystify it
First, determine what type of documentation this session needs:
Use when the session involved:
- Choosing between technology options (e.g., "Fastify vs Express")
- Making architectural choices (e.g., "Monorepo structure")
- Defining patterns or conventions (e.g., "How we handle auth")
- Design decisions with long-term impact
Characteristics:
- Forward-looking and prescriptive
- Answers "Why do we do it this way?"
- Referenced when making similar future decisions
- Long-lived documentation
Examples:
- "Why We Use Better Auth Instead of Custom Auth"
- "Monorepo Architecture: Apps vs Packages"
- "State Management: Why Zustand Over Redux"
Use when the session involved:
- Debugging and fixing issues
- Discovering how something works
- Trial-and-error problem solving
- Implementation insights from building features
Characteristics:
- Backward-looking and descriptive
- Answers "How did we solve this?"
- Referenced when similar issues arise
- Captures the journey, not just the destination
Examples:
- "Fixing Render Monorepo Build Errors"
- "Debugging OTP Email Delivery Issues"
- "How @Mentions Feature Was Implemented"
Default to learnings/ unless it's clearly an architectural decision that will guide future work.
If it's BOTH (e.g., you chose a technology AND learned implementation details), create it in decisions/ and include a "Key Learnings" section.
Ask yourself: "Did this session result in a significant architectural or design decision?"
- Yes → Create in
docs/decisions/ - No → Create in
docs/learnings/
For Decisions:
- Location:
docs/decisions/[descriptive-name].md - Naming: Use kebab-case, no date prefix (e.g.,
fastify-over-express.md)
For Learnings:
- Location:
docs/learnings/YYYY-MM-DD-[short-title].md - Naming: Date prefix + kebab-case (e.g.,
2026-02-04-render-build-fix.md)
# [Decision Title]
**Decision Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated
**Deciders:** [Who was involved in this decision]
## Context
[What is the issue we're trying to solve? What's the background?]
## Decision
[What did we decide to do?]
## Options Considered
### Option 1: [Name]
**Description:** [Brief description]
**Pros:**
- [Pro 1]
- [Pro 2]
**Cons:**
- [Con 1]
- [Con 2]
### Option 2: [Name]
[Same structure]
### Option 3: [Name]
[Same structure]
## Rationale
[Why did we choose this option over the others? What were the key factors?]
## Consequences
**Positive:**
- [Benefit 1]
- [Benefit 2]
**Negative:**
- [Trade-off 1]
- [Trade-off 2]
**Neutral:**
- [Impact 1]
## Implementation Notes
[Any specific guidance for implementing this decision]
## Related Decisions
- [Link to related decision doc]
## References
- [External docs, articles, or discussions that informed this decision]
## Key Learnings (Optional)
[If you learned something valuable during implementation, capture it here]# [Short Title]
**Date:** YYYY-MM-DD
**Context:** [One-line description of what we were trying to do]
## Problem
[What was broken? What error were we seeing? What behavior was unexpected?]
## Attempts
- **Attempt 1:** [What we tried] → [Why it didn't work]
- **Attempt 2:** [What we tried] → [Why it didn't work]
- **Attempt 3:** [What we tried] → [Result]
## Solution
[What actually fixed it? Be specific - file paths, line numbers, config changes]
```typescript
// Include relevant code snippets
```
## Root Cause
[Why was this happening? What was the underlying issue?]
## Key Learnings
- [Insight 1]
- [Insight 2]
- [Pattern or best practice discovered]
## Related Files
- `path/to/file1.ts` - [What changed and why]
- `path/to/file2.config.js` - [What changed and why]
## Future Reference
[Anything to remember for next time? Any gotchas to watch out for?]For Both Types:
- Write like notes, not like AI-generated documentation
- Focus on the "why" and the "aha moments"
- Flag anything that still feels magical or unclear
- Include inline code snippets or config examples if relevant
- Keep it concise and actionable
For Decisions:
- Be explicit about trade-offs
- Document alternatives even if not chosen
- Update status if the decision changes later
For Learnings:
- Capture the journey, not just the solution
- Include failed attempts (they're valuable!)
- Make it searchable for future similar issues
Filename: docs/decisions/fastify-over-express.md
# Why We Use Fastify Instead of Express
**Decision Date:** 2026-01-15
**Status:** Accepted
**Deciders:** Sourav + AI
## Context
We needed a backend framework for `apps/server`. The server handles API requests from web and mobile apps.
## Decision
We chose Fastify as our backend framework.
## Options Considered
### Option 1: Express
**Pros:**
- Industry standard, huge ecosystem
- Massive community and resources
- Team familiarity
**Cons:**
- Not TypeScript-first
- Slower performance
- No built-in schema validation
### Option 2: Fastify
**Pros:**
- TypeScript-first with excellent type inference
- Built-in schema validation (TypeBox)
- 2x faster than Express
- Active maintenance
**Cons:**
- Smaller ecosystem
- Less familiar to most developers
### Option 3: Hono
**Pros:**
- Lightweight and edge-ready
- Modern API design
**Cons:**
- Too new, smaller ecosystem
- Optimized for edge, we're using Node
## Rationale
TypeScript support and schema validation were critical. Fastify's TypeBox integration gives us type-safe APIs with minimal boilerplate.
## Consequences
**Positive:**
- Better DX with TypeScript
- Automatic API validation
- Better performance
**Negative:**
- Team needs to learn Fastify patterns
- Fewer plugins than Express
## Implementation Notes
Use TypeBox for all route schemas. See `apps/server/src/routes/` for examples.Filename: docs/learnings/2026-02-04-render-build-fix.md
# Render Monorepo Build Fix
**Date:** 2026-02-04
**Context:** Server deployment kept failing on Render with module resolution errors
## Problem
Build failed with:
```
Error: Cannot find module '@beenthere/db'
```
## Attempts
- **Attempt 1:** Added `yarn build:packages` → Still failed
- **Attempt 2:** Modified turbo filters → Still failed
- **Attempt 3:** Used `workspace:*` protocol → **WORKED**
## Solution
In `apps/server/package.json`:
```json
"dependencies": {
"@beenthere/db": "workspace:*"
}
```
## Root Cause
Render doesn't auto-resolve workspace packages like local dev.
## Key Learnings
- Always use `workspace:*` for monorepo deps in production
- Build order matters: packages before apps
## Related Files
- `apps/server/package.json` - Added workspace dependency
## Future Reference
This applies to any monorepo deployment platform.Decisions helps us maintain consistency and explain "why we do it this way" to future engineers.
Learnings prevents us from repeating the same debugging steps and preserve hard-won insights.
Together, they build institutional knowledge that compounds over time.