aws-samples / aws-samples/sample-spec-driven-presentation-maker
refactor: unify builtin template note storage between local and cloud
- Dominant language
- Python
- Stars
- 128
- Forks
- 10
- Avg merge
- 4d 40m
- Merged PRs (30d)
- 8
Description
## Background
Per-user notes on builtin templates were added in #204 (cloud) and extended to local mode + L1 CLI in #209. The two paths ended up with structurally different data models for the same concept:
| | Cloud (L3/L4) | Local (L1/L2/local Web UI) |
|---|---|---|
| Storage | DDB item `BUILTIN_NOTE#` per user — first-class entity | `state.json` → `template_metadata["builtin:"].description` — field inside the analysis-cache entry |
| Merge point | Tool layer (`mcp-server/tools/template.py` + `storage.get_builtin_template_notes()`) | Engine (`sdpm.api.list_templates_with_metadata` knows the `builtin:` key convention) |
## Why this is debt
1. **User data and regenerable cache share one entry** in local state.json. Clearing the analysis cache risks wiping user notes; every writer must carefully preserve `description` (see the `PATCH /api/templates/builtin/[name]` route).
2. **Inverted dependency**: the `builtin:` key convention originated in the local Web UI listing route; the engine now follows a consumer's convention (vs. "Engine is source of truth").
3. **Asymmetry trap**: the cloud path does not use `list_templates_with_metadata` at all. Anyone consolidating L3 onto the engine could silently break note resolution. (Documented in the engine docstring since #209, but documentation is a mitigation, not a fix.)
## Proposed direction
- Move local notes to a dedicated `template_notes` section in `state.json` (mirroring the cloud separation), with a one-time migration from `template_metadata["builtin:"].description`.
- Have consumers merge notes at their layer (like cloud does), or pass notes to the engine as an explicit parameter — removing the `builtin:`/plain dual-key lookup from `list_templates_with_metadata`.
- Keep the legacy fallback for one minor version, then drop it (pre-1.0).
## Non-goals
- No cloud-side changes — the DDB `BUILTIN_NOTE#` model is the reference design.
- No behavior change for end users.
Refs: #166, #204, #209
Contributor guide
Research direction
Start by reading sdpm.api.list_templates_with_metadata, mcp-server/tools/template.py, storage.get_builtin_template_notes(), and the PATCH /api/templates/builtin/[name] route, then trace how state.json stores template_metadata. Done means local notes use a dedicated template_notes section with a one-time migration, consumers or the engine merge notes explicitly, and the legacy fallback remains for one minor version.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100