red/.planning/phases/01-foundation/01-CONTEXT.md

# Phase 1: Foundation - Context

**Gathered:** 2026-03-19
**Status:** Ready for planning

<domain>
## Phase Boundary

Next.js project scaffold, local PostgreSQL database with auth schema, and single-agent authentication — the infrastructure every subsequent phase depends on. Scope ends at: agent can log in, session persists, protected routes redirect, and the app runs locally. Eventual target is a home Docker server.

</domain>

<decisions>
## Implementation Decisions

### Login page
- Branded design — Teressa's logo, brand colors, and photo
- Route: `/agent/login`
- Title/headline: "Agent Portal"
- Generic error message on failed login: "Invalid email or password" (does not hint whether email exists)
- No forgot-password flow in this phase (Teressa is sole user — reset via env var or direct DB update)
- Password visibility toggle included (show/hide)
- Post-login redirect: `/agent/dashboard`

### Session behavior
- 7-day rolling session — refreshes on each visit
- Persistent across browser restarts (httpOnly cookie, not sessionStorage)
- On session expiry: silent redirect to `/agent/login`
- Logout: immediate redirect to `/agent/login` with "You've been signed out" confirmation message

### Database schema
- Auth tables only in this phase (users + sessions) — future phases own their own migrations
- ORM: Drizzle ORM (TypeScript-native, excellent Next.js + Neon support)
- Password storage: bcrypt hashing
- Migration files committed to repo in `/drizzle` directory (version-controlled, auditable)
- Initial account: seed script creates Teressa's account from environment variables (no signup UI)
- Single-agent design — standard users table rows, no multi-tenant role/status columns

### Deployment
- Local development: `npm run dev` at `localhost:3000`
- Database: local PostgreSQL (Docker recommended: `postgres:16` container)
- Secrets managed via `.env.local` (never committed to repo)
- No external cloud services — no Vercel, no Neon, no Blob storage in this phase
- Eventual target: home server running Docker Compose (Next.js container + PostgreSQL container)
- File storage (Phase 4+): local filesystem / Docker volume — no Vercel Blob

### Claude's Discretion
- Exact brand color palette and visual design details (Teressa's brand assets to be used but layout specifics are open)
- Loading/submitting state on the login form button
- Exact bcrypt salt rounds
- Session token storage implementation details (Auth.js/NextAuth vs custom JWT)

</decisions>

<specifics>
## Specific Ideas

- The login page should feel like it belongs to Teressa's real estate brand, not a generic SaaS admin panel
- "Agent Portal" as the label clearly signals purpose without being verbose

</specifics>

<deferred>
## Deferred Ideas

- Forgot password / email reset flow — add to backlog for a future phase
- Multi-agent support / role-based access — intentionally deferred, single-agent product for now
- Staging or preview environments — production-only for this build; can revisit if testing complexity grows

</deferred>

---

*Phase: 01-foundation*
*Context gathered: 2026-03-19*