kite/.planning/STATE.md

gsd_state_version, milestone, milestone_name, current_phase, status, last_updated, progress

gsd_state_version	milestone	milestone_name	current_phase	status	last_updated	progress
1.0	v1.0	milestone	1	executing	2026-05-22T08:30:00Z	total_phases completed_phases total_plans completed_plans percent 5 0 5 3 60

Project State

Project: DocuVault Status: Executing Phase 1 Current Phase: 1 Last Updated: 2026-05-22

Phase Status

Phase	Name	Status
1	Infrastructure Foundation	In Progress (3/5 plans)
2	Users & Authentication	Not Started
3	Document Migration & Multi-User Isolation	Not Started
4	Folders, Sharing, Quotas & Document UX	Not Started
5	Cloud Storage Backends	Not Started

Current Position

Phase: 1 (Infrastructure Foundation) — EXECUTING Plan: 4 of 5 Phase: 01-infrastructure-foundation Plan: 01-03 COMPLETE → advancing to 01-04 Progress: ██████░░░░ 60%

Performance Metrics

Metric	Value
Phases complete	0 / 5
Requirements mapped	54 / 54
Plans written	5 (Phase 1)
Plans complete	3

Accumulated Context

Key Decisions

Decision	Rationale
PostgreSQL + MinIO	Multi-user quotas and horizontal scaling require shared, consistent state
HKDF per-user key derivation	Single Fernet key would be catastrophic on leak — must be derived before first credential is stored
Presigned MinIO URL flow	FastAPI handles metadata only; bytes never pass through the API layer
Atomic PostgreSQL quota UPDATE	Never perform quota arithmetic in Python between two DB statements
JWT in httpOnly cookie	Refresh token in httpOnly cookie; access token in Pinia memory only — never localStorage
Refresh token family revocation	RFC 9700 — reuse of a rotated token revokes entire family and alerts user
BackgroundTasks replacement	FastAPI BackgroundTasks is per-instance; replace with Celery+Redis or pgqueuer before horizontal scale
AuditLog metadata_ ORM attribute	metadata is reserved on DeclarativeBase; ORM attribute is metadata_ with name="metadata" kwarg to avoid silent collision
documents.user_id nullable Phase 1	D-03 — no auth in Phase 1; Phase 2 migration adds NOT NULL after auth lands
groups stub table Phase 1	D-02 — groups is a v2 feature; table created now for schema completeness, no rows until Phase 2+
SEQUENCES grants in migration	GRANT USAGE/SELECT on sequences required for audit_log.id autoincrement nextval() by docuvault_app
Admin impersonation excluded	Explicit architectural exclusion — no endpoint or UI pathway; violates privacy-first core value
Two-DSN PostgreSQL strategy	DATABASE_URL (docuvault_app, DML only) + DATABASE_MIGRATE_URL (docuvault_migrate, DDL only); celery-worker gets only DATABASE_URL
MinIO healthcheck via mc ready local	curl removed from MinIO Docker image since Oct 2023; mc is the correct in-container healthcheck tool
pydantic-settings v2 SettingsConfigDict	SettingsConfigDict API used (not deprecated class Config form) for env var config
async_client fixture name	Distinct from legacy sync client fixture to avoid collision; both coexist until Plan 05
xfail(strict=False) for Wave 0	All pre-implementation scaffolds use strict=False so unexpected passes don't break CI

Open Questions

• Celery + Redis vs pgqueuer for Phase 3 (depends on Redis availability in deployment target)
• Verify cloud SDK minor versions on PyPI before Phase 5 pinning
• Confirm PyOTP valid_window default in current docs (recommend valid_window=1 for ±30s clock drift)
• Audit existing codebase for any bcrypt hashes before removing passlib in Phase 2

Blockers

None.

Session Continuity

Updated at each phase transition.

Field	Value
Last session	2026-05-22 — Executed 01-03-PLAN.md (SQLAlchemy ORM + Alembic migration; alembic upgrade head verified)
Next action	Execute 01-04-PLAN.md (StorageBackend ABC + MinIO backend + async services/storage.py)
Pending decisions	See Open Questions above