# 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.