Document Note Backend

Batch 11 · file-backed FastAPI notes service on port 8091 · real CRUD + aggregate · shell-integrated with honest offline fallback to localStorage · local/dev only

Spec Scaffold Batch 11 · v1.0 Planning A-owned Local/dev · file-backed · NOT production

Access · สิทธิ์

Overview · ภาพรวม

The Batch-11 notes backend ends browser-only persistence. A FastAPI service at /runtime/document-note-service/ (port 8091 default) provides CRUD + aggregate endpoints. The Universal Document Shell calls the backend when reachable; otherwise it falls back to the Batch-6 localStorage path with a visible OFFLINE badge.

Backend Batch 11 ปิดการพึ่ง browser อย่างเดียว · FastAPI ที่ port 8091 · shell เรียก backend ก่อน · ถ้าไม่ถึงใช้ localStorage แบบ offline ที่มีป้ายชัด

Key Point

Notes now persist across browsers via a real backend. Local/dev only · single-writer · no auth on notes endpoints.
Notes เก็บข้ามเบราว์เซอร์ได้ด้วย backend จริง · local/dev · writer เดียว · endpoint ไม่มี auth

Summary · สรุป

7 endpoints: health, create, list, patch, delete, aggregate, by-doc. Storage is a single JSON file rewritten atomically on every mutation. 14-field schema from Batch 6 is honored byte-for-byte. When the backend is up, the shell writes there; when it is down, localStorage takes over.

7 endpoints · เก็บไฟล์ JSON เดียว · rewrite แบบ atomic · schema 14 ฟิลด์เหมือน Batch 6 · backend ทำงาน = เขียนไป backend · ไม่ทำงาน = ใช้ localStorage

Endpoints

Method	Path	Purpose
GET	`/api/notes/health`	liveness + counts
POST	`/api/notes/create`	create note (doc_id + title required)
GET	`/api/notes/list[?doc_id=…]`	list (optionally filtered)
PATCH	`/api/notes/{note_id}`	status / linked_change_ref / title / body / priority
DELETE	`/api/notes/{note_id}`	hard delete
GET	`/api/notes/aggregate`	counters + top-5 open docs + recent activity
GET	`/api/notes/by-doc`	per-doc summary

Full contract: notes_contract.json

Persistence

Single JSON store at docs/runtime/document-note-service/notes_store.json
Atomic write via temp-file + os.replace
No fsync in this batch (acceptable for dev)
Single-writer assumption · never run multiple uvicorn workers
Delete the store file to reset the backlog

Shell integration

On DOMContentLoaded, document-shell.js probes /api/notes/health. When OK, NOTES_MODE='backend' and the notes tab rewires its create/list/patch/delete through the backend. When probe fails, NOTES_MODE='offline' and the Batch-6 localStorage path stays active. The mode is rendered in the summary counter under Backing.

Base URL: <html data-ds-notes-base> → window.DS_NOTES_BASE → default http://127.0.0.1:8091. Set none to disable.

Offline fallback

When the backend is unreachable, the shell continues the Batch-6 localStorage path for the current browser. Aggregate/backlog views read from whichever source is live — backend first, local second — and the page shows the active mode honestly.

Notes created offline stay browser-local until you manually POST them to /api/notes/create. Automatic re-sync is deferred to Batch 12+.

Honest limits

No auth on note endpoints · anyone reaching the service can write
No transition history · only last_action_at
Single-writer · multi-worker corrupts state
No offline→online re-sync · notes created offline stay offline until manual migration
No notifications · no SSE · no websocket
No rate limiting
Aggregate is O(n) · fine for small backlog

Checklist · Batch 12+

☐ Per-note auth · inherit session identity
☐ Audit trail of status transitions
☐ SQLite or Postgres back-end
☐ Multi-worker safety (row-level locks)
☐ Offline→online re-sync utility
☐ Notifications for P0 creation
☐ CSV / JSON bulk export

References

Change log

Date	Change
2026-04-20	v1.0 · initial · Batch 11

Notes · โน้ต

Backing: backend when reachable · localStorage fallback. Check the summary counter above.