specs/002-fullstack-ui-integration/quickstart.md

Quickstart Guide: Full-Stack Integration & UI Experience

Feature: 002-fullstack-ui-integration Date: 2026-01-09 Purpose: Testing and validation guide for integration and UI polish

Overview

This guide helps developers and reviewers quickly set up, test, and validate the Full-Stack Integration & UI Experience feature. Since this feature builds on existing implementations (Specs 1 & 2), most setup is already complete.

Prerequisites

Before testing this feature, ensure:

1. Specs 1 & 2 are complete:

   • ✅ Task CRUD endpoints working (Spec 1)
   • ✅ Authentication & JWT working (Spec 2)
   • ✅ Database migrations applied
   • ✅ Environment variables configured

2. Development environment:

   • Node.js 18+ installed
   • Python 3.11+ installed
   • PostgreSQL database accessible (Neon or local)
   • Git repository cloned

Quick Setup (5 minutes)

1. Backend Setup

# Navigate to backend directory
cd backend

# Install dependencies (if not already done)
pip install -r requirements.txt

# Verify environment variables
cat .env
# Should contain:
# - DATABASE_URL
# - BETTER_AUTH_SECRET
# - JWT_ALGORITHM=HS256
# - JWT_EXPIRATION_DAYS=7

# Apply migrations (if not already done)
python -m alembic upgrade head

# Start backend server
python -m uvicorn src.main:app --reload

# Server should start at http://localhost:8000
# Verify: Open http://localhost:8000/docs (Swagger UI)

2. Frontend Setup

# Navigate to frontend directory (in new terminal)
cd frontend

# Install dependencies (if not already done)
npm install

# Verify environment variables
cat .env.local
# Should contain:
# - NEXT_PUBLIC_API_URL=http://localhost:8000
# - BETTER_AUTH_SECRET (same as backend)

# Start frontend server
npm run dev

# Server should start at http://localhost:3000
# Verify: Open http://localhost:3000

3. Verify Setup

Backend Health Check:

curl http://localhost:8000/health
# Expected: {"status":"healthy"}

Frontend Access:

• Open http://localhost:3000
• Should redirect to http://localhost:3000/auth/signin
• Signin page should load without errors

Testing User Stories

P1: Complete Authentication Flow (MVP)

Test Scenario: New user signup → signin → task management

Steps:

1. Navigate to signup:

   Open: http://localhost:3000/auth/signup
   

2. Test validation errors:

   • Try empty email → Should show "Email is required"
   • Try invalid email (e.g., "notanemail") → Should show "Invalid email format"
   • Try weak password (e.g., "pass") → Should show password requirements
   • Try short name → Should show "Name is required"

3. Create account:

   • Email: test@example.com
   • Password: TestPass123
   • Name: Test User
   • Click "Sign Up"
   • Expected: Redirect to signin page with success message

4. Sign in:

   • Email: test@example.com
   • Password: TestPass123
   • Click "Sign In"
   • Expected: Redirect to home page (http://localhost:3000)

5. Verify authenticated state:

   • Header should show "Welcome, Test User"
   • "Sign Out" button should be visible
   • Task form and list should be visible

6. Sign out:

   • Click "Sign Out" button
   • Expected: Redirect to signin page
   • Expected: Cannot access home page without signin

Pass Criteria:

• ✅ Validation errors display inline
• ✅ Signup creates account successfully
• ✅ Signin issues JWT token
• ✅ Home page shows user profile
• ✅ Sign out clears session

---

P2: Responsive UI States

Test Scenario: Loading, empty, and error states

Steps:

1. Test loading state:

   • Sign in as test user
   • Observe task list loading
   • Expected: Loading spinner with "Loading tasks..." message
   • Expected: Spinner disappears when tasks load

2. Test empty state:

   • If no tasks exist:
   • Expected: "No tasks yet" message
   • Expected: Call-to-action to create first task
   • Expected: Empty state is centered and clear

3. Test error state:

   • Stop backend server (Ctrl+C in backend terminal)
   • Try to create a task
   • Expected: Error message "Unable to connect to server"
   • Expected: Retry button appears
   • Restart backend server
   • Click retry button
   • Expected: Operation succeeds

4. Test form loading state:

   • Create a task
   • Observe submit button during API call
   • Expected: Button shows "Creating..." and is disabled
   • Expected: Button returns to normal after success

5. Test token expiration (optional - requires waiting 7 days or manual token manipulation):

   • With expired token, try to access home page
   • Expected: Redirect to signin with "Session expired" message

Pass Criteria:

• ✅ Loading states appear within 100ms
• ✅ Empty states provide clear guidance
• ✅ Error messages are actionable
• ✅ Form buttons show loading state
• ✅ Token expiration handled gracefully

---

P3: Responsive Design

Test Scenario: Mobile, tablet, desktop layouts

Steps:

1. Test desktop layout (≥1024px):

   • Open browser DevTools (F12)
   • Set viewport to 1920x1080
   • Expected: Three-column layout
   • Expected: Task form (left), filters (middle), task list (right)

2. Test tablet layout (768px-1023px):

   • Set viewport to 768x1024
   • Expected: Two-column layout
   • Expected: Task form and filters stacked (left), task list (right)

3. Test mobile layout (<768px):

   • Set viewport to 375x667 (iPhone SE)
   • Expected: Single-column layout
   • Expected: All elements stacked vertically
   • Expected: No horizontal scrolling

4. Test touch targets:

   • On mobile viewport, inspect buttons
   • Expected: All buttons are at least 44x44px
   • Expected: Adequate spacing between interactive elements

5. Test signin/signup forms:

   • Navigate to signin page on mobile
   • Expected: Form is centered and readable
   • Expected: Input fields use appropriate types (email, password)
   • Expected: Keyboard doesn't obscure form fields

Pass Criteria:

• ✅ Layouts adapt to viewport width
• ✅ No horizontal scrolling on any device
• ✅ Touch targets are 44x44px minimum
• ✅ Forms are usable on mobile
• ✅ Text is readable without zooming

---

P4: Centralized API Communication

Test Scenario: Verify API client consistency

Steps:

1. Verify JWT token inclusion:

   • Sign in as test user
   • Open browser DevTools → Network tab
   • Create a task
   • Inspect POST /api/tasks request
   • Expected: Authorization header present: Bearer <token>

2. Verify 401 handling:

   • Clear localStorage (DevTools → Application → Local Storage → Clear)
   • Try to access home page
   • Expected: Automatic redirect to signin
   • Expected: No console errors

3. Verify error formatting:

   • Sign in
   • Stop backend server
   • Try to create a task
   • Open browser console
   • Expected: APIError with status, detail, error_code
   • Expected: Error displayed in UI (not just console)

4. Verify all endpoints use fetchAPI:

   • Review code: frontend/src/lib/api.ts
   • Expected: All API functions use fetchAPI helper
   • Expected: No direct fetch() calls in components

Pass Criteria:

• ✅ JWT tokens included automatically
• ✅ 401 errors trigger signin redirect
• ✅ Errors formatted consistently
• ✅ All API calls use centralized client
• ✅ No unhandled promise rejections

---

P5: Environment Coordination

Test Scenario: Setup and configuration

Steps:

1. Verify environment variables:

   # Backend
   grep BETTER_AUTH_SECRET backend/.env
   
   # Frontend
   grep BETTER_AUTH_SECRET frontend/.env.local
   
   # Expected: Both values match exactly
   

2. Test with missing environment variable:

   • Temporarily rename backend/.env to backend/.env.backup
   • Try to start backend
   • Expected: Clear error message about missing variables
   • Restore backend/.env

3. Test with mismatched secrets:

   • Change BETTER_AUTH_SECRET in frontend/.env.local
   • Sign in
   • Expected: Token verification fails
   • Expected: Clear error message
   • Restore correct secret

4. Verify README documentation:

   • Read backend/README.md
   • Expected: Authentication setup instructions present
   • Expected: Environment variable documentation
   • Read frontend/README.md
   • Expected: Better Auth configuration notes
   • Expected: Setup instructions

Pass Criteria:

• ✅ Environment variables documented
• ✅ Missing variables show clear errors
• ✅ Mismatched secrets are detected
• ✅ README files are up-to-date
• ✅ Setup takes under 10 minutes

---

Common Issues & Solutions

Issue: "404 Not Found" on /api/auth/signup

Cause: Auth router not registered in backend/src/main.py

Solution:

# In backend/src/main.py, ensure:
from .api.routes import tasks, auth

app.include_router(auth.router)  # Must be present
app.include_router(tasks.router)

Issue: "Token signature verification failed"

Cause: BETTER_AUTH_SECRET differs between frontend and backend

Solution:

# Verify secrets match:
grep BETTER_AUTH_SECRET backend/.env
grep BETTER_AUTH_SECRET frontend/.env.local

# If different, copy backend secret to frontend

Issue: "Unable to connect to database"

Cause: DATABASE_URL is incorrect or database is not running

Solution:

# For Neon PostgreSQL:
# Verify connection string in backend/.env includes ?sslmode=require

# For local PostgreSQL:
# Ensure PostgreSQL is running:
# Windows: Check Services
# Mac/Linux: sudo systemctl status postgresql

Issue: Frontend shows blank page

Cause: JavaScript error or build issue

Solution:

# Check browser console for errors
# Clear Next.js cache:
cd frontend
rm -rf .next
npm run dev

Issue: Tasks not loading

Cause: JWT token missing or invalid

Solution:

# Check localStorage in browser DevTools:
# Application → Local Storage → http://localhost:3000
# Look for 'auth_session' key

# If missing or invalid, sign out and sign in again

Performance Benchmarks

Expected Performance:

• Loading states appear: <100ms
• Page transitions: <500ms
• API responses: <200ms
• Task list load (10 tasks): <300ms
• Signup/signin: <1s

How to Measure:

// In browser console:
performance.mark('start');
// Perform action (e.g., create task)
performance.mark('end');
performance.measure('action', 'start', 'end');
console.log(performance.getEntriesByType('measure'));

Validation Checklist

Before marking this feature complete, verify:

Authentication Flow:

• Signup form validates inputs
• Signup creates user in database
• Signin issues JWT token
• Home page shows user profile
• Sign out clears session

UI States:

• Loading spinners appear during async operations
• Empty states show helpful messages
• Error messages are clear and actionable
• Form buttons show loading state

Responsive Design:

• Desktop layout (3 columns) works at 1920px
• Tablet layout (2 columns) works at 768px
• Mobile layout (1 column) works at 375px
• No horizontal scrolling on any device
• Touch targets are 44x44px minimum

API Communication:

• JWT tokens included in all requests
• 401 errors trigger signin redirect
• Errors formatted consistently
• No unhandled promise rejections

Environment Setup:

• Backend starts without errors
• Frontend starts without errors
• Environment variables documented
• README files are accurate

Next Steps

After validating all user stories:

1. Mark tasks complete in tasks.md
2. Document any issues found during testing
3. Create git commit with implementation
4. Prepare for demo (if hackathon submission)

Support

For issues or questions:

• Review specification: specs/002-fullstack-ui-integration/spec.md
• Review implementation plan: specs/002-fullstack-ui-integration/plan.md
• Check API reference: specs/002-fullstack-ui-integration/contracts/existing-api-reference.yaml
• Review existing specs: specs/001-auth-security/