aws-samples / aws-samples/sample-spec-driven-presentation-maker

refactor: unify builtin template note storage between local and cloud

Open
#222 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.