curo1305
5.7 KiB
Phase 1: Infrastructure Foundation - 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-21 Phase: 1-Infrastructure Foundation Areas discussed: Schema scope, App wiring, Background worker, Env / secrets strategy
Schema Scope
| Option | Description | Selected |
|---|---|---|
| Full v1 skeleton | All tables upfront: users, refresh_tokens, quotas, documents, topics, folders, shares, audit_log, cloud_connections | ✓ |
| Phase 1 minimum | Only documents + topics tables; users and auth added in Phase 2 | |
| You decide | Leave scope to planner |
User's choice: Full v1 skeleton Notes: —
| Option | Description | Selected |
|---|---|---|
| Yes, seed the groups table | Empty table, correct columns and FKs; avoids schema change when v2 Group admin lands | ✓ |
| No, v1 tables only | Keep Phase 1 strictly to v1 requirements |
User's choice: Yes, seed the groups table Notes: PROJECT.md explicitly notes groups table will be seeded in schema.
| Option | Description | Selected |
|---|---|---|
| Leave existing data on filesystem; schema empty at Phase 1 end | Phase 3 runs migration script | |
| Seed a system / placeholder user | Sentinel user_id for Phase 1 uploads |
User's choice: (Free text) "The current documents and files are just test data and can be deleted. Please switch uploads to PostgreSQL and MinIO." Notes: Existing flat-file data is expendable test data. This changed the Phase 1 scope significantly: the storage service layer is rewritten in Phase 1, not Phase 3. Phase 3's data migration scope is removed.
App Wiring
| Option | Description | Selected |
|---|---|---|
| Filesystem stays active; new infra sits ready | Phase 1 only wires infra; Phase 3 switches service layer | |
| Phase 1 switches uploads to PostgreSQL + MinIO | services/storage.py rewritten in Phase 1 | ✓ |
User's choice: Phase 1 switches uploads to PostgreSQL + MinIO Notes: User clarified existing data is test data and can be deleted.
| Option | Description | Selected |
|---|---|---|
| Seed a default/admin user in Phase 1 migration | All Phase 1 uploads attributed to placeholder user | |
| Make user_id nullable for Phase 1, enforce NOT NULL in Phase 2 | Avoids phantom user; Phase 2 adds constraint | ✓ |
User's choice: user_id nullable in Phase 1 Notes: —
| Option | Description | Selected |
|---|---|---|
| Leave data/ directory in place | Stop writing to it; clean up manually or in Phase 3 | |
| Delete data/ contents in Phase 1 | Clean break; no ambiguity about active storage | ✓ |
User's choice: Delete data/ contents in Phase 1 Notes: Old data is test data only.
| Option | Description | Selected |
|---|---|---|
| Single bucket 'docuvault' with user prefix paths | Standard S3 pattern; matches STORE-02 key schema | ✓ |
| Per-user buckets | Stronger isolation but bucket count issues and operational complexity |
User's choice: Single bucket 'docuvault' Notes: —
Background Worker
| Option | Description | Selected |
|---|---|---|
| pgqueuer | Postgres-native; no Redis; simpler Compose | |
| Celery + Redis | Battle-tested; adds Redis service | ✓ |
User's choice: Celery + Redis Notes: —
| Option | Description | Selected |
|---|---|---|
| Phase 1 — add it now with the other infra | All services wired together in one shot | ✓ |
| Phase 3 — add when horizontal scaling needed | STORE-08 is a Phase 3 requirement |
User's choice: Phase 1 — add Redis + Celery now Notes: Redis also serves as the rate-limiting store for Phase 2 auth endpoints.
Env / Secrets Strategy
User asked for best practice guidance before answering — wanted to understand production VPS implications (root server / VPS deployment, database admin password handling). Claude explained:
- App should never use PostgreSQL superuser; restricted users per principle of least privilege
- Secrets stored outside project directory at
/etc/docuvault/env;chmod 600, service user owned - Two DB DSNs: runtime (restricted) + migration (DDL privileges)
| Option | Description | Selected |
|---|---|---|
| .env gitignored + .env.example committed | Docker Compose native; self-hosters copy .env.example → .env | ✓ |
| Hardcoded dev defaults in docker-compose.yml | Simpler but secrets committed to git | |
| docker-compose.override.yml for secrets | Flexible but extra indirection layer |
User's choice: .env gitignored + .env.example committed; production at /etc/docuvault/env
| Env var group | Selected |
|---|---|
| DATABASE_URL + DATABASE_MIGRATE_URL | ✓ |
| MINIO_ENDPOINT / MINIO_ROOT_USER / MINIO_ROOT_PASSWORD / MINIO_BUCKET | ✓ |
| REDIS_URL | ✓ |
| SECRET_KEY | ✓ |
Notes: All four groups introduced in Phase 1. SECRET_KEY documented now for Phase 2+ use (JWT + HKDF) even though Phase 1 doesn't read it.
| Option | Description | Selected |
|---|---|---|
| Yes — provision restricted users in Phase 1 | init script creates docuvault_app + docuvault_migrate | ✓ |
| No — use superuser for now, split in Phase 2 | Simpler but not least-privilege |
User's choice: Yes — provision restricted users in Phase 1 Notes: —
Claude's Discretion
None — user made explicit choices for all areas.
Deferred Ideas
None — discussion stayed within phase scope.