Business-Management/features/storage-service/CLAUDE.md

storage-service — Claude context

Unified file/blob storage microservice, port 8020 (internal). All services must use this service's HTTP API for any file persistence — no service may write to a Docker volume directly. See root CLAUDE.md for architecture, Docker, and project-wide workflows.

---

Architecture rule (enforced)

No service may write to a filesystem path for persistent data. All file/blob storage must go through the storage-service HTTP API. Violation is a security/architecture defect.

---

File & Folder Tree

features/storage-service/
├── app/
│   ├── main.py                          ← FastAPI, lifespan (backend init)
│   ├── core/config.py                   ← Settings (DATA_DIR, STORAGE_BACKEND, S3_*, WEBDAV_*)
│   ├── routers/
│   │   ├── health.py                    ← GET /health
│   │   ├── objects.py                   ← PUT/GET/DELETE /objects/{bucket}/{key:path}, GET /objects/{bucket}
│   │   └── migrate.py                   ← POST /migrate, GET /migrate/status, DELETE /migrate, PATCH /backend-config
│   └── services/
│       ├── backend_manager.py           ← build_backend(), initialize_backend(), get_backend(), switch_backend()
│       ├── migration.py                 ← run_migration(), get_status(), cancel(); KNOWN_BUCKETS
│       └── backends/
│           ├── base.py                  ← AbstractStorageBackend (ABC)
│           ├── local.py                 ← LocalFSBackend — /data/storage/{bucket}/{key}
│           ├── s3.py                    ← S3Backend — aiobotocore, endpoint_url configurable
│           └── webdav.py                ← WebDAVBackend — aiohttp + WebDAV PROPFIND/PUT/GET/DELETE
├── scripts/
│   ├── start.sh                         ← prod start (uvicorn port 8020)
│   └── start_dev.sh                     ← dev start (uvicorn --reload)
├── Dockerfile                           ← python:3.12-slim, non-root user 1001
└── STATUS.md

---

HTTP API

Objects

Method	Path	Body	Response
PUT	/objects/{bucket}/{key:path}	Raw bytes	204
GET	/objects/{bucket}/{key:path}	—	200 Raw bytes / 404
DELETE	/objects/{bucket}/{key:path}	—	204
GET	/objects/{bucket}	—	{"bucket": "...", "keys": [...]}

Keys may contain / (e.g. user123/abc.pdf). Path traversal (..) returns 400.

Migration

Method	Path	Body	Response
POST	/migrate	{"driver": "s3", "config": {...}}	202 / 400 / 409
GET	/migrate/status	—	{state, total, done, failed, errors[]}
DELETE	/migrate	—	204 / 409
PATCH	/backend-config	{"driver": "...", "config": {...}}	204 / 400 / 409

Migration states: idle → validating → migrating → switching → cleaning → done (or failed/cancelled)

Health

Method	Path	Response
GET	/health	{"status": "ok", "backend": "local"}

---

Buckets

Bucket	Contents	Key format
documents	Uploaded PDFs	{user_id}/{doc_id}.pdf or watch/{doc_id}.pdf
config	JSON config files	{service_name}_config.json

To add a new bucket: add it to KNOWN_BUCKETS in services/migration.py so it is included in migrations.

---

Backend drivers

Driver	Config fields	Notes
local	data_dir (optional)	Default. Files under /data/storage/. Zero external deps.
s3	endpoint_url, access_key, secret_key, region	Works with MinIO, AWS S3, Backblaze B2, Cloudflare R2. Set endpoint_url="" for real AWS.
webdav	url, username, password, root_path	Nextcloud: set root_path to /remote.php/dav/files/{username}

---

Adding a new backend driver

1. Create app/services/backends/your_driver.py implementing AbstractStorageBackend
2. Add a branch in build_backend() in backend_manager.py
3. Add config fields to app/core/config.py if env-based config is needed
4. Document driver name + config fields in this file

---

Default Values & Limits

Parameter	Value	Location
Default backend	local	STORAGE_BACKEND env var
Local data dir	/data/storage	DATA_DIR env var
S3 region default	us-east-1	S3_REGION env var
Migration error cap in response	50	migration.py
Port	8020	scripts/start.sh