Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

refactor: unify builtin template note storage between local and cloud

Open
  • Is something wrong?
#222 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
45/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Quiet
Tech stack
python
Domain
backend

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.

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#<name> per user — first-class entity state.json → template_metadata["builtin:<name>"].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:<name>"].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

Dominant language
Python
Stars
130
Forks
10
Avg merge
4h 31m
Merged PRs (30d)
58

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

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

All issues in aws-samples/sample-spec-driven-presentation-maker

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.