From 226a50ea10bcd077e287c9be2f3585a8cb62ec0a Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Thu, 23 Apr 2026 11:08:36 -0500
Subject: [PATCH] Update storage docs

---
 PLAN.md              | 3 +++
 README.md            | 2 +-
 docs/architecture.md | 4 ++--
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/PLAN.md b/PLAN.md
index 5ff70c5..c60f83e 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -14,6 +14,9 @@
 - Installable React PWA shell with offline-ready game prep scaffolding.
 - Docker-based local development stack.
 
+## Storage Status
+- Backend media persists in the `backend-media` named Docker volume.
+
 ## Known Constraints
 - TeamSnap entities should not be durably mirrored on the backend.
 - Gameday lineup changes are local state in v1.
diff --git a/README.md b/README.md
index beb60f2..e4f8e5a 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ Walkup is a collaborative baseball walk-up song app built as a React PWA with a
 ## Stack
 - Frontend: React, TypeScript, Vite, React Router, TanStack Query, `teamsnap.js`, `vite-plugin-pwa`
 - Backend: FastAPI, SQLAlchemy, Pydantic Settings, HTTPX
-- Infra: Docker Compose, Postgres, local object-style file storage
+- Infra: Docker Compose, Postgres, named Docker volume for backend media
 
 ## Repository Layout
 - `frontend/`: React PWA
diff --git a/docs/architecture.md b/docs/architecture.md
index 27480fd..54b6a43 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -22,7 +22,7 @@ Walkup is a baseball walk-up song app with a React PWA frontend and a FastAPI ba
 - `backend/` contains the FastAPI application.
 - The backend handles TeamSnap OAuth start, callback, and token refresh.
 - It manages session state, clip metadata, game assignment state, and normalized media storage.
-- Media files are stored locally in the backend storage path during development.
+- Media files are stored in the `backend-media` Docker volume, mounted at `/app/storage` during development.
 
 ## Data Boundaries
 
@@ -34,5 +34,5 @@ Walkup is a baseball walk-up song app with a React PWA frontend and a FastAPI ba
 
 - Docker Compose is the normal development path.
 - The frontend is served separately through Vite in development.
-- The backend is run through FastAPI with local storage and Docker secrets for TeamSnap credentials.
+- The backend is run through FastAPI with Docker-managed local storage and Docker secrets for TeamSnap credentials.
 - `README.md` contains the setup steps and environment expectations.