feat: email, invites, and oauth

Author: cofin

.env.local.example

@@ -1,29 +1,104 @@
-# App
-SECRET_KEY='secret-key'
+# App Configuration
+SECRET_KEY='your-secret-key-here'
 LITESTAR_DEBUG=true
 LITESTAR_HOST=0.0.0.0
-LITESTAR_PORT=8089
-APP_URL=http://localhost:${LITESTAR_PORT}
+LITESTAR_PORT=8000
+APP_URL=http://localhost:8000
+LOG_LEVEL=20
 
-LOG_LEVEL=10
-# Database
-DATABASE_ECHO=true
-DATABASE_ECHO_POOL=true
+# Database Configuration
+DATABASE_ECHO=false
+DATABASE_ECHO_POOL=false
 DATABASE_POOL_DISABLE=false
-DATABASE_POOL_MAX_OVERFLOW=5
+DATABASE_POOL_MAX_OVERFLOW=10
 DATABASE_POOL_SIZE=5
 DATABASE_POOL_TIMEOUT=30
-DATABASE_URL=postgresql+psycopg://app:app@localhost:15432/app
+DATABASE_USER=app
+DATABASE_PASSWORD=app
+DATABASE_HOST=localhost
+DATABASE_PORT=5432
+DATABASE_DB=app
+DATABASE_URL=postgresql://${DATABASE_USER}:${DATABASE_PASSWORD}@${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_DB}
 
-REDIS_URL=redis://localhost:16379/0
+# Redis Configuration
+REDIS_URL=redis://localhost:6379/0
 
-# Worker
-SAQ_USE_SERVER_LIFESPAN=True
+# Worker Configuration
+SAQ_USE_SERVER_LIFESPAN=False
 SAQ_WEB_ENABLED=True
 SAQ_BACKGROUND_WORKERS=1
 SAQ_CONCURRENCY=1
 
+# Frontend Configuration
 VITE_HOST=localhost
-VITE_PORT=5174
-VITE_HOT_RELOAD=True
-VITE_DEV_MODE=True
+VITE_PORT=3006
+ALLOWED_CORS_ORIGINS=["localhost:3006","localhost:8080","localhost:8000"]
+
+# Storage Configuration
+APP_SCRATCH_PATH=/tmp/app
+
+# Email Configuration (SMTP)
+EMAIL_ENABLED=true  # Set to true to enable email sending
+EMAIL_SMTP_HOST=localhost  # For MailHog: localhost, for production: your SMTP host
+EMAIL_SMTP_PORT=1025  # For MailHog: 1025, for production: 587 (TLS) or 465 (SSL)
+EMAIL_SMTP_USER=  # MailHog doesn't require auth, leave empty for dev
+EMAIL_SMTP_PASSWORD=  # MailHog doesn't require auth, leave empty for dev
+EMAIL_USE_TLS=false  # MailHog doesn't use TLS, set true for production
+EMAIL_USE_SSL=false  # MailHog doesn't use SSL, set true for production
+EMAIL_FROM_ADDRESS=noreply@localhost  # Default from email
+EMAIL_FROM_NAME="Litestar Dev App"  # Default from name
+EMAIL_TIMEOUT=30  # SMTP connection timeout in seconds
+
+# OAuth Configuration
+
+# Keycloak (Local Development OAuth Server)
+# ==========================================
+# Access Keycloak admin at: http://localhost:18080 (admin/admin)
+# Create a client with these settings for development OAuth testing
+OAUTH_ENABLED=true
+GOOGLE_CLIENT_ID=litestar-app  # Your Keycloak client ID
+GOOGLE_CLIENT_SECRET=your-client-secret  # Generated in Keycloak client settings
+GOOGLE_REDIRECT_URI=http://localhost:3000/auth/google/callback
+
+# Production Google OAuth (replace Keycloak values above when deploying)
+# GOOGLE_CLIENT_ID=your-production-google-client-id
+# GOOGLE_CLIENT_SECRET=your-production-google-client-secret
+# GOOGLE_REDIRECT_URI=https://yourdomain.com/auth/google/callback
+
+# MailHog (Development Email Testing)
+# ====================================
+# Access MailHog web UI at: http://localhost:8025
+# MailHog SMTP server runs on: localhost:1025
+# MailHog catches all emails sent to it during development
+
+# Example Production Email Provider Configurations:
+# =================================================
+
+# Gmail (requires app password):
+# EMAIL_SMTP_HOST=smtp.gmail.com
+# EMAIL_SMTP_PORT=587
+# [email protected]
+# EMAIL_SMTP_PASSWORD=your-app-password
+# EMAIL_USE_TLS=true
+# EMAIL_USE_SSL=false
+
+# SendGrid:
+# EMAIL_SMTP_HOST=smtp.sendgrid.net
+# EMAIL_SMTP_PORT=587
+# EMAIL_SMTP_USER=apikey
+# EMAIL_SMTP_PASSWORD=your-sendgrid-api-key
+# EMAIL_USE_TLS=true
+
+# AWS SES:
+# EMAIL_SMTP_HOST=email-smtp.us-east-1.amazonaws.com
+# EMAIL_SMTP_PORT=587
+# EMAIL_SMTP_USER=your-ses-smtp-username
+# EMAIL_SMTP_PASSWORD=your-ses-smtp-password
+# EMAIL_USE_TLS=true
+
+# Mailgun:
+# EMAIL_SMTP_HOST=smtp.mailgun.org
+# EMAIL_SMTP_PORT=587
+# [email protected]
+# EMAIL_SMTP_PASSWORD=your-mailgun-password
+# EMAIL_USE_TLS=true

.pre-commit-config.yaml

@@ -24,7 +24,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.11.12"
+    rev: "v0.11.13"
     hooks:
       # Run the linter.
       - id: ruff

CLAUDE.md

@@ -7,9 +7,12 @@ This file provides essential guidance for Claude Code when working with the Lite
 ```bash
 # Setup
 make install                    # Fresh installation
-cp .env.local.example .env      # Setup environment  
-make start-infra                # Start PostgreSQL + Redis
+cp .env.local.example .env      # Setup environment
+make start-infra                # Start PostgreSQL + Redis + MailHog + Keycloak
+make keycloak-setup             # Configure Keycloak OAuth client
 uv run app run                  # Start all services
+make mailhog                    # Open MailHog web UI (email testing)
+make keycloak                   # Open Keycloak admin (OAuth testing)
 
 # Development
 make types                      # Generate TypeScript types (ALWAYS after schema changes!)
@@ -70,13 +73,13 @@ from app.db import models as m
 
 class UserService(service.SQLAlchemyAsyncRepositoryService[m.User]):
     """Service for user operations."""
-    
+
     class Repo(repository.SQLAlchemyAsyncRepository[m.User]):
         """User repository."""
         model_type = m.User
-    
+
     repository_type = Repo
-    
+
     # Custom service methods here
 ```
 
@@ -141,10 +144,32 @@ make test-all
    - `make test`
    - `make check-all`
 
+## 📧 Email Development with MailHog
+
+MailHog is configured for development email testing:
+
+- **Web UI**: <http://localhost:18025> (view all emails)
+- **SMTP Server**: localhost:11025 (app sends emails here)
+- **Access**: `make mailhog` to open web interface
+- **Configuration**: Already set in `.env.local.example`
+
+All emails sent during development are caught by MailHog instead of being delivered.
+
+## 🔐 OAuth Development with Keycloak
+
+Keycloak provides a local OAuth server for development:
+
+- **Admin Console**: <http://localhost:18080> (admin/admin)
+- **Auto Setup**: `make keycloak-setup` to configure OAuth client
+- **Access**: `make keycloak` to open admin interface
+- **Test User**: testuser / testpass123 (created automatically)
+- **Configuration**: Client credentials provided by setup script
+
 ## 📊 Current Work Context
 
 - Email verification: ✅ Implemented
-- Password reset: ✅ Implemented  
+- Password reset: ✅ Implemented
+- Email service: ✅ SMTP with MailHog for dev
 - 2FA/TOTP: ✅ Implemented (configurable)
 - OAuth: Backend ✅ | Frontend ❌ | Tests ❌
 - Production validation: Backend 70% ✅ | Frontend ❌ | Tests ❌

Makefile

@@ -215,6 +215,37 @@ infra-logs:                                           ## Tail development infras
 	@echo "${INFO} Tailing infrastructure logs... 📋"
 	@docker compose -f tools/deploy/docker/docker-compose.infra.yml logs -f
 
+.PHONY: mailhog
+mailhog:                                              ## Open MailHog web interface
+	@echo "${INFO} Opening MailHog web interface... 📧"
+	@echo "${INFO} MailHog UI: http://localhost:18025"
+	@echo "${INFO} SMTP Server: localhost:11025"
+	@if command -v open >/dev/null 2>&1; then \
+		open http://localhost:18025; \
+	elif command -v xdg-open >/dev/null 2>&1; then \
+		xdg-open http://localhost:18025; \
+	else \
+		echo "${WARN} Please open http://localhost:18025 in your browser"; \
+	fi
+
+.PHONY: keycloak
+keycloak:                                             ## Open Keycloak admin console
+	@echo "${INFO} Opening Keycloak admin console... 🔐"
+	@echo "${INFO} Keycloak Admin: http://localhost:18080"
+	@echo "${INFO} Username: admin | Password: admin"
+	@if command -v open >/dev/null 2>&1; then \
+		open http://localhost:18080; \
+	elif command -v xdg-open >/dev/null 2>&1; then \
+		xdg-open http://localhost:18080; \
+	else \
+		echo "${WARN} Please open http://localhost:18080 in your browser"; \
+	fi
+
+.PHONY: keycloak-setup
+keycloak-setup:                                       ## Setup Keycloak with development OAuth client
+	@echo "${INFO} Setting up Keycloak for development... 🔧"
+	@bash tools/deploy/docker/keycloak-setup.sh
+
 .PHONY: start-all
 start-all:                                        ## Start local containers
 	@echo "${INFO} Starting local infrastructure... 🚀"

docs/architecture/01-overview.md

@@ -178,4 +178,4 @@ Now that you understand the high-level architecture:
 
 ---
 
-*This overview provides the foundation for understanding the Litestar Fullstack SPA architecture. Each subsequent section will dive deeper into specific aspects of the system.*
+*This overview provides the foundation for understanding the Litestar Fullstack SPA architecture. Each subsequent section will dive deeper into specific aspects of the system.*

docs/architecture/02-project-structure.md

@@ -86,7 +86,7 @@ from advanced_alchemy.base import UUIDAuditBase
 class User(UUIDAuditBase):
     """User account model."""
     __tablename__ = "user_account"
-    
+
     email: Mapped[str] = mapped_column(String(255), unique=True)
     is_verified: Mapped[bool] = mapped_column(default=False)
 ```
@@ -116,10 +116,10 @@ from litestar.plugins.sqlalchemy import service, repository
 
 class UserService(service.SQLAlchemyAsyncRepositoryService[User]):
     """Handles user operations."""
-    
+
     class Repo(repository.SQLAlchemyAsyncRepository[User]):
         model_type = User
-    
+
     repository_type = Repo
 ```
 
@@ -189,7 +189,7 @@ export function TeamList() {
     queryKey: ["teams"],
     queryFn: () => api.teams.listTeams()
   });
-  
+
   return (
     <div className="grid gap-4">
       {teams?.map(team => (
@@ -289,7 +289,7 @@ services:
       POSTGRES_PASSWORD: app
     ports:
       - "5432:5432"
-  
+
   redis:
     image: redis:7-alpine
     ports:
@@ -376,4 +376,4 @@ Continue to [Backend Architecture](03-backend-architecture.md) for deep dive int
 
 ---
 
-*This structure promotes scalability, maintainability, and developer productivity. Each directory has a clear purpose, making it easy to locate and organize code.*
+*This structure promotes scalability, maintainability, and developer productivity. Each directory has a clear purpose, making it easy to locate and organize code.*