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

Phase 1: Foundation - Context

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

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

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

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

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

---

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