kite/.planning/phases/03-document-migration-multi-user-isolation/03-DISCUSSION-LOG.md

Phase 3: Document Migration & Multi-User Isolation - Discussion Log

Audit trail only. Do not use as input to planning, research, or execution agents. Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

Date: 2026-05-23 Phase: 3-Document Migration & Multi-User Isolation Areas discussed: Null-user record cleanup, Upload bytes flow, Topics isolation model, Settings flat-file retirement

---

Null-user record cleanup

Q1: How to handle existing documents with user_id=NULL before NOT NULL migration?

Option	Description	Selected
Delete them	Dev/test data — Phase 1 D-04 deleted flat-file data with same reasoning. Pre-migration script deletes all NULL-user documents + MinIO objects.	✓
Assign to first admin	Script sets user_id = first admin's id for all NULL rows. Data preserved but attributed to admin.
Fail migration if any exist	Guard in Alembic migration; manual cleanup required before re-run.

User's choice: Delete them

---

Q2: Delete MinIO objects along with DB rows?

Option	Description	Selected
Delete both DB rows and MinIO objects	Script calls storage_backend.delete_object() before deleting row. No orphaned objects.	✓
DB rows only	Simpler, but leaves orphaned null-user/... objects in MinIO.

User's choice: Delete both DB rows and MinIO objects

---

Q3: Cleanup as standalone script or baked into Alembic migration?

Option	Description	Selected
Baked into Alembic migration	upgrade() runs cleanup first, then adds NOT NULL. One command, one atomic flow.	✓
Standalone script	Separate scripts/cleanup_null_user_docs.py, must be run manually before migration.

User's choice: Baked into Alembic migration

---

Q4: Reconcile quota used_bytes during migration?

Option	Description	Selected
Yes, reconcile quotas	UPDATE quotas SET used_bytes = actual sum of document sizes per user. Accurate starting state.	✓
No, quotas start at zero	All quotas reset to 0; accurate from first upload via new enforcement.

User's choice: Yes, reconcile quotas

---

Upload bytes flow

Q1: Presigned PUT URLs vs bytes-through-FastAPI?

Option	Description	Selected
Keep bytes through FastAPI	Current flow preserved. 'Presigned URL flow' refers to download presigning only.
Implement presigned PUT URLs in Phase 3	Direct-to-MinIO uploads per CLAUDE.md architectural rule. Requires frontend changes.	✓

User's choice: Implement presigned PUT URLs in Phase 3

---

Q2: How should the presigned upload flow work end-to-end?

Option	Description	Selected
Two-step: initiate + confirm	POST upload-url → PUT to MinIO → POST confirm. Clean separation.	✓
One-step with webhook/polling	MinIO event notification webhook. More complex.

User's choice: Two-step: initiate + confirm

---

Q3: Handling abandoned uploads?

Option	Description	Selected
Let them expire naturally (Celery cleanup)	Celery beat deletes pending rows older than 1 hour + MinIO objects. No quota reserved for pending.	✓
Quota reserved on initiate, released on timeout	Reserve at step 1, refund on timeout. More complex.
No cleanup — pending rows stay	Orphaned but harmless. Not recommended for production.

User's choice: Let them expire naturally (Celery beat cleanup)

---

Q4: When to enforce quota?

Option	Description	Selected
At confirm (Recommended)	Atomic quota UPDATE runs at /confirm. File size from MinIO stat (authoritative).	✓
At initiation with client-supplied size	Reserve quota at step 1. Requires trusting client-supplied size or verifying at confirm.

User's choice: At confirm

---

Topics isolation model

Q1: How should the topics namespace work?

Option	Description	Selected
System defaults (user_id=NULL) + per-user overrides	Union of system topics + user's own topics. Admin manages system topics. DOC-04 compliant.	✓
Fully isolated per user	Own complete topic namespace per user. No shared topics.
Fully global (shared)	All topics shared. Simplest but violates topic privacy.

User's choice: System defaults + per-user overrides

---

Q2: Who can create system-level topics?

Option	Description	Selected
Admin only via /api/admin/topics	Only admin creates/edits/deletes system topics. Regular users CRUD own topics.	✓
Any user can promote a topic to system	Requires admin approval flow — defer to v2.
Admin and users both create to own namespace	Same result as option 1.

User's choice: Admin only via /api/admin/topics

---

Q3: What happens to existing topics (currently all user_id=NULL)?

Option	Description	Selected
Keep as system topics	They become system defaults automatically. Admin can delete unwanted ones.
Delete all existing topics	Fresh start — dev/test data. Admin seeds system topics after Phase 3.	✓

User's choice: Delete all existing topics

---

Q4: What topics does AI classification see?

Option	Description	Selected
System topics + user's own topics	Union of user_id=NULL and user_id=current_user.id. New suggestions go into user namespace.	✓
User's topics only	Classifier only sees personal topics. New user starts with empty list.

User's choice: System topics + user's own topics; new suggestions created in user's namespace

---

Settings flat-file retirement

Q1: What happens to /api/settings and settings.json?

Option	Description	Selected
Keep settings.json for system prompt + provider defaults only	Remove AI API key config. Keep system_prompt and defaults. /api/settings becomes read-only.
Remove /api/settings entirely in Phase 3	Clean break. All AI config from DB. System prompt → env var.	✓
Keep /api/settings as-is but auth-gate it	Backward compat with flat-file. Technical debt preserved.

User's choice: Remove /api/settings entirely

---

Q2: Where does the system prompt live after /api/settings is removed?

Option	Description	Selected
Env var SYSTEM_PROMPT with code default fallback	SYSTEM_PROMPT env var, optional. Code default in classifier.py if not set.	✓
New system_config DB table	Flexible but adds schema + endpoint complexity.
Per-user system prompts from users table	Highly flexible but out of Phase 3 scope.

User's choice: SYSTEM_PROMPT env var with hardcoded code default

---

Q3: How does Celery task resolve AI config?

Option	Description	Selected
Look up from doc.user_id → users.ai_provider/ai_model	Task has document_id → fetch doc → fetch user → AI config. Correct per-user isolation.	✓
Pass user_id as a task argument	Upload confirm endpoint passes user_id to task. Avoids extra DB query for doc row.

User's choice: Look up from doc.user_id → users.ai_provider/ai_model

---

Q4: Fallback when user has no ai_provider assigned?

Option	Description	Selected
DEFAULT_AI_PROVIDER + DEFAULT_AI_MODEL env vars	Optional env vars in config.py with safe code default (ollama/llama3.2).	✓
Hardcoded fallback to ollama	Simpler, requires code change to switch later.
Raise an error	Classification fails if no provider assigned. Admin must assign before uploads work.

User's choice: DEFAULT_AI_PROVIDER + DEFAULT_AI_MODEL env vars

---

Claude's Discretion

None — all major decisions were made by user.

Deferred Ideas

• Presigned GET URLs for document downloads — Phase 4 (DOC-02: PDF preview proxied through app)
• Per-user system prompt overrides — out of scope for v1
• Quota reservation at upload-url initiation — decided against; confirm-time enforcement preferred
• MinIO event notification webhook approach — deferred in favor of two-step confirm