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 hundreds of plan dirs.
| Domain | File |
|---|---|
| Auth & sessions | decisions/auth.md |
| Permissions & RBAC | decisions/permissions.md |
| Multi-tenancy | decisions/multi-tenancy.md |
| MCP tooling | decisions/mcp.md |
| Broadcasting & real-time | decisions/broadcasting.md |
| Reports & feedback | decisions/reports.md |
| Notifications | decisions/notifications.md |
| Attachments & files | decisions/attachments.md |
| Time tracking | decisions/time-tracking.md |
| AI features | decisions/ai-features.md |
| CLI & distribution | decisions/cli.md |
| Integrations (GitHub, Stripe, Mattermost) | decisions/integrations.md |
| Issues, sprints, epics, board | decisions/issues-board.md |
| UI conventions | decisions/ui-conventions.md |
| Platform & infra | decisions/platform.md |
Provenance
Distilled from the DECISIONS.md files and bug reports that accumulated 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.
The sources: frontmatter in each file is the authoritative record of what has been folded in, listing every source dir by path plus a Skipped (...) line for issues examined that yielded no real tradeoff. It is written by the distilling agent as it goes, so it cannot drift from the entries the way a hand-maintained tally does.
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.