3. Deployment scope: local single-user

  • Status: Accepted

  • Date: 2026-06-13

Context

“Personal study assistant” could mean several things, and the interpretation decides whether authentication and multi-tenancy exist as concerns at all. Three options were considered:

  1. Local single-user — runs on the developer’s machine via Docker Compose; one user, no auth, secrets via .env. Simplest; CI builds and tests images but does not deploy.

  2. Cloud-deployable, single-user — same single-user model but designed to deploy to a cloud host (managed Postgres, registry push, prod vs. local config). More infra surface — and the local bge models are heavy to host in the cloud anyway (see ADR 0002).

  3. Multi-user with auth — per-user corpora and authentication from day one. The most infrastructure: an auth layer, per-user data isolation, and user migrations. Overkill for a personal tool unless it will be shared.

Decision

Adopt local single-user: the system runs on the developer’s machine via Docker Compose, with no authentication and secrets supplied through .env. A single corpus, a single user.

To avoid a future rewrite, the database schema keeps a user_id seam (a user_id column on the relevant tables, defaulted for the single local user) so authentication and per-user isolation can be layered on later without restructuring the data model — but none of that is built now.

Consequences

  • Simplest possible footprint: no auth layer, no session/JWT handling, no per-user isolation logic. Development effort goes into retrieval and orchestration instead.

  • Secrets live in .env, documented via .env.example. This is acceptable for a single-user local tool and is not a model for a shared deployment.

  • CI builds and tests images but does not deploy — there is no cloud target, registry push, or prod configuration to maintain.

  • The user_id seam preserves an upgrade path to authenticated multi-user use; adopting it later would mean adding an auth layer and populating the seam, not reshaping the schema.

  • This decision aligns the deployment story with ADR 0002: on-machine models and an on-machine, single-user runtime reinforce the same all-local goal.