Appearance
Engineering Knowledge
Distilled wisdom from the Kendo app codebase — the parts that aren't visible in code.
What lives here
The Kendo app repo (~/Code/kendo) is the authoritative source for how it works now:
~/Code/kendo/CLAUDE.md— top-level conventions, skills, workflow~/Code/kendo/ARCHITECTURE.md— system architecture~/Code/kendo/backend/CLAUDE.md— backend rules (Action pattern, DTOs, transactions)~/Code/kendo/frontend/CLAUDE.md— frontend rules (components, composables, stores)
This folder is why we built it that way — content that disappears if you only read code:
- The alternative we rejected and the reason we chose the current approach
- Iterations that didn't work before the shipped one
- Surprises discovered during implementation
- Cross-cutting patterns that recurred across multiple plans
- Bug root causes — why something slipped past tests into prod
Layout
| File | Scope |
|---|---|
| lessons-learned.md | Cross-cutting wisdom: recurring traps, "next time" rules |
| postmortems.md | Bug postmortems — root cause and what changed |
decisions/<domain>.md | Per-domain decision logs — chose / rejected / why (see Domain coverage below) |
Domain coverage
The decisions/ folder splits by feature domain so a search for "broadcast" or "auth" lands in one focused file instead of 145 plan dirs.
| Domain | File | Issues covered |
|---|---|---|
| Auth & sessions | decisions/auth.md | 15 |
| Permissions & RBAC | decisions/permissions.md | 12 |
| Multi-tenancy | decisions/multi-tenancy.md | 17 |
| MCP tooling | decisions/mcp.md | 19 |
| Broadcasting & real-time | decisions/broadcasting.md | 18 |
| Reports & feedback | decisions/reports.md | 14 |
| Notifications | decisions/notifications.md | 11 |
| Attachments & files | decisions/attachments.md | 13 |
| Time tracking | decisions/time-tracking.md | 9 |
| AI features | decisions/ai-features.md | 10 |
| CLI & distribution | decisions/cli.md | 6 |
| Integrations (GitHub, Stripe, Mattermost) | decisions/integrations.md | 10 |
| Issues, sprints, epics, board | decisions/issues-board.md | 33 |
| UI conventions | decisions/ui-conventions.md | 30 |
| Platform & infra | decisions/platform.md | 17 |
Provenance
Distilled from 145 DECISIONS.md files and 36 bug postmortems in ~/Code/kendo/docs/plans/ and ~/Code/kendo/docs/bugs/ — those source dirs were deleted after this wiki was verified, since their unique value is captured here and their implementation lives in the codebase.
Each decision entry cites the originating issue (e.g., Source: KD-0067) — search Kendo or git log for full historical context.
Conventions for contributors
- New decisions go straight here, not into a new
plans/doc — plans now live on feature branches alongside the implementation, and get folded into these domain files when shipped. - Don't write what the code already shows. If a reader can
grepfor it, don't put it here. - Each entry is short: Chose + Rejected + Why + Source. Anything longer is probably reiterating the implementation.