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

Implementation Plan: Full-Stack Integration & UI Experience

Branch: 002-fullstack-ui-integration | Date: 2026-01-09 | Spec: spec.md Input: Feature specification from /specs/002-fullstack-ui-integration/spec.md

Note: This template is filled in by the /sp.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

This feature focuses on integrating and polishing existing functionality from Specs 1 (Task CRUD) and 2 (Authentication & API Security) into a cohesive, professional user experience. The primary requirement is to ensure seamless end-to-end flows with proper UI feedback (loading states, empty states, error handling), responsive design across devices, and centralized API communication. The technical approach emphasizes frontend refinement, consistent error handling patterns, and responsive layout implementation using existing Next.js App Router and Tailwind CSS infrastructure.

Technical Context

Language/Version:

• Frontend: TypeScript 5.x with Next.js 16+ (App Router)
• Backend: Python 3.11+ with FastAPI (already implemented)

Primary Dependencies:

• Frontend: Next.js 16+, React 18+, TypeScript 5.x, Tailwind CSS 3.x, Better Auth
• Backend: FastAPI, SQLModel, PyJWT, passlib (already implemented in Specs 1 & 2)

Storage: PostgreSQL (Neon Serverless) - already configured with User and Task tables

Testing:

• Frontend: Manual testing of UI states, responsive layouts, and user flows
• Backend: Existing API endpoints already tested in Specs 1 & 2
• Integration: End-to-end testing of authentication → task management flow

Target Platform:

• Web browsers (Chrome, Firefox, Safari, Edge - latest 2 versions)
• Responsive design for mobile (320px), tablet (768px), and desktop (1920px)

Project Type: Web application (frontend + backend monorepo)

Performance Goals:

• Loading states appear within 100ms of user action
• Page transitions complete within 500ms
• API responses within 200ms (backend already optimized in Spec 1)
• Smooth 60fps animations and transitions

Constraints:

• No new backend endpoints (reuse existing from Spec 1)
• No new authentication mechanisms (reuse JWT from Spec 2)
• Tailwind CSS only (no inline styles or CSS files)
• Next.js App Router patterns (server components by default)
• Must work in local development environment

Scale/Scope:

• 5 user stories (P1-P5) focused on integration and polish
• ~10-15 frontend component refinements
• Responsive layouts for 3 breakpoints (mobile, tablet, desktop)
• Centralized API client with error handling
• Environment configuration documentation

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Principle I: User-Centric Functionality ✅ PASS

Evaluation: This feature directly serves end-users by improving UX through clear feedback mechanisms (loading, empty, error states), responsive design, and seamless authentication flows. All 5 user stories focus on user experience improvements.

Alignment:

• P1 (Authentication Flow): Ensures users can easily sign up and sign in
• P2 (UI States): Provides clear feedback during all operations
• P3 (Responsive Design): Makes app accessible on all devices
• P4 (API Communication): Ensures reliable backend communication
• P5 (Environment Setup): Enables developers/reviewers to run the app

Verdict: ✅ Fully aligned - all features directly benefit end-users

Principle II: Spec-Driven Development ✅ PASS

Evaluation: This implementation follows the Spec-Kit Plus workflow. The specification (spec.md) defines 5 prioritized user stories with 30 acceptance scenarios. This plan.md will generate research.md, data-model.md, contracts/, and quickstart.md before tasks.md generation.

Alignment:

• Specification created via /sp.specify command
• Planning via /sp.plan command (this document)
• Tasks will be generated via /sp.tasks command
• Implementation via /sp.implement command
• All code references specs in /specs/002-fullstack-ui-integration/

Verdict: ✅ Fully aligned - follows spec-driven workflow

Principle III: Security & Data Privacy ✅ PASS

Evaluation: This feature builds on Spec 2 (Authentication & API Security) which already implements JWT authentication, user data isolation, and secure token handling. No new security mechanisms are introduced - this feature focuses on UI integration of existing security.

Alignment:

• JWT authentication already implemented (Spec 2)
• User data isolation already enforced (Spec 2)
• API client will include JWT tokens automatically (FR-012)
• 401 errors trigger signin redirect (FR-014)
• No hardcoded secrets (uses environment variables)

Verification:

• ✅ No new authentication mechanisms
• ✅ Reuses existing JWT verification from Spec 2
• ✅ Frontend API client includes Authorization headers
• ✅ Error handling preserves security (generic error messages)

Verdict: ✅ Fully aligned - builds on existing security implementation

Principle IV: Scalable Architecture ✅ PASS

Evaluation: This feature maintains the stateless architecture established in Specs 1 & 2. The centralized API client (P4) improves maintainability without changing the stateless JWT-based design. Responsive design (P3) ensures the frontend scales across devices.

Alignment:

• Stateless API design maintained (JWT-based)
• No server-side sessions introduced
• Frontend components remain reusable
• API client centralizes communication logic
• Responsive design supports multiple devices

Verification:

• ✅ No state stored on backend (JWT tokens only)
• ✅ Frontend components are composable
• ✅ API client is a shared utility (not per-component)
• ✅ Responsive layouts use Tailwind breakpoints

Verdict: ✅ Fully aligned - maintains scalable architecture

Principle V: Maintainable & Consistent Code ✅ PASS

Evaluation: This feature enforces consistency through centralized API communication (P4), standardized error handling, and Tailwind CSS usage. The focus on loading/empty/error states creates consistent patterns across all components.

Alignment:

• Centralized API client (fetchAPI function)
• Consistent error handling across all API calls
• Tailwind CSS utilities for all styling (FR-020)
• Reusable loading/empty/error state components
• Next.js App Router patterns maintained

Verification:

• ✅ All API calls use centralized fetchAPI function
• ✅ Error responses formatted consistently
• ✅ Loading states follow same pattern
• ✅ Tailwind CSS only (no inline styles)

Verdict: ✅ Fully aligned - improves code consistency

Key Standards Compliance

API Compliance ✅ PASS

• Reuses existing REST endpoints from Spec 1
• No new endpoints introduced
• API client handles errors consistently (FR-013)
• 401 responses trigger signin redirect (FR-014)

Database Integrity ✅ PASS

• No database changes required
• Reuses existing User and Task tables from Specs 1 & 2
• No new migrations needed

Frontend Quality ✅ PASS

• Next.js App Router patterns (server components by default)
• Client components for interactivity (forms, buttons)
• Responsive design for mobile, tablet, desktop (P3)
• Tailwind CSS for all styling (FR-020)

Authentication ✅ PASS

• Better Auth already implemented (Spec 2)
• JWT tokens already issued and verified (Spec 2)
• Frontend includes JWT in Authorization header (FR-012)
• Token expiry handled with signin redirect (FR-006)

Spec Adherence ✅ PASS

• Implementation references spec.md
• All 20 functional requirements documented
• 5 user stories with acceptance criteria
• No implementation without spec

Constraints Compliance

Tech Stack ✅ PASS

• Frontend: Next.js 16+ (App Router), TypeScript, Tailwind CSS ✅
• Backend: FastAPI, SQLModel ✅ (no changes)
• Database: Neon PostgreSQL ✅ (no changes)
• Authentication: Better Auth (JWT) ✅ (no changes)

Endpoint Authorization ✅ PASS

• All task endpoints already require JWT (Spec 2)
• No new endpoints introduced
• API client includes JWT automatically (FR-012)

Monorepo Structure ✅ PASS

• Maintains existing structure
• CLAUDE.md files already in place
• specs/002-fullstack-ui-integration/ created
• No structural changes required

No Manual Coding ✅ PASS

• All implementation via Claude Code
• References specifications
• Follows spec-driven workflow

Security ✅ PASS

• JWT token expiry already implemented (7 days, Spec 2)
• BETTER_AUTH_SECRET shared via environment variables
• No new security mechanisms introduced

Constitution Check Summary

Overall Verdict: ✅ APPROVED - All principles, standards, and constraints satisfied

Justification: This is an integration and polish feature that builds on existing implementations from Specs 1 and 2. It introduces no new architectural patterns, security mechanisms, or backend logic. The focus is entirely on frontend refinement and user experience improvements, which aligns perfectly with constitutional principles.

No Violations: No complexity justification required.

Project Structure

Documentation (this feature)

specs/002-fullstack-ui-integration/
├── spec.md              # Feature specification (completed)
├── plan.md              # This file (in progress)
├── research.md          # Phase 0 output (to be generated)
├── data-model.md        # Phase 1 output (to be generated)
├── quickstart.md        # Phase 1 output (to be generated)
├── contracts/           # Phase 1 output (to be generated)
│   └── existing-api-reference.yaml
├── checklists/
│   └── requirements.md  # Specification validation (completed)
└── tasks.md             # Phase 2 output (NOT created by /sp.plan)

Source Code (repository root)

# Web application structure (frontend + backend monorepo)

backend/
├── src/
│   ├── api/
│   │   ├── deps.py              # JWT verification (Spec 2) ✅
│   │   └── routes/
│   │       ├── auth.py          # Auth endpoints (Spec 2) ✅
│   │       └── tasks.py         # Task CRUD (Spec 1) ✅
│   ├── core/
│   │   ├── config.py            # Environment config ✅
│   │   ├── database.py          # DB connection ✅
│   │   └── security.py          # JWT & password hashing (Spec 2) ✅
│   ├── models/
│   │   ├── user.py              # User model (Spec 2) ✅
│   │   └── task.py              # Task model (Spec 1) ✅
│   ├── schemas/
│   │   ├── auth.py              # Auth schemas (Spec 2) ✅
│   │   └── task.py              # Task schemas (Spec 1) ✅
│   ├── services/
│   │   ├── auth_service.py      # Auth logic (Spec 2) ✅
│   │   └── task_service.py      # Task logic (Spec 1) ✅
│   └── main.py                  # FastAPI app ✅
├── alembic/
│   └── versions/                # Migrations (Specs 1 & 2) ✅
├── tests/                       # Backend tests (future)
├── .env                         # Backend environment variables ✅
└── requirements.txt             # Python dependencies ✅

frontend/
├── src/
│   ├── app/
│   │   ├── layout.tsx           # Root layout with AuthProvider ✅
│   │   ├── page.tsx             # Home page (protected) ✅
│   │   ├── auth/
│   │   │   ├── signin/
│   │   │   │   └── page.tsx     # Signin page (Spec 2) ✅
│   │   │   └── signup/
│   │   │       └── page.tsx     # Signup page (Spec 2) ✅
│   │   └── globals.css          # Global Tailwind styles ✅
│   ├── components/
│   │   ├── auth/
│   │   │   ├── SignInForm.tsx   # Signin form (Spec 2) ✅
│   │   │   └── SignUpForm.tsx   # Signup form (Spec 2) ✅
│   │   └── tasks/
│   │       ├── TaskForm.tsx     # Create task (Spec 1) ✅
│   │       ├── TaskItem.tsx     # Task display (Spec 1) ✅
│   │       ├── TaskList.tsx     # Task list (Spec 1) ✅
│   │       └── TaskFilters.tsx  # Filters (Spec 1) ✅
│   ├── lib/
│   │   ├── api.ts               # API client (needs refinement) 🔄
│   │   ├── auth.ts              # Auth session (Spec 2) ✅
│   │   └── types.ts             # TypeScript types ✅
│   └── providers/
│       └── AuthProvider.tsx     # Auth context (Spec 2) ✅
├── public/                      # Static assets
├── .env.local                   # Frontend environment variables ✅
├── package.json                 # Node dependencies ✅
├── tailwind.config.ts           # Tailwind configuration ✅
└── tsconfig.json                # TypeScript configuration ✅

specs/
├── 001-auth-security/           # Spec 2 (Authentication) ✅
└── 002-fullstack-ui-integration/ # This feature (in progress)

Structure Decision: The existing web application structure is maintained. This feature focuses on refining frontend components and the API client rather than adding new files. Key areas of work:

1. API Client Refinement (frontend/src/lib/api.ts):

   • Already includes JWT token injection ✅
   • Already handles 401 redirects ✅
   • Needs: Consistent error formatting, loading state management

2. Component Enhancements:

   • Add loading states to all async operations
   • Add empty states to TaskList
   • Add error states with retry buttons
   • Improve responsive layouts

3. Responsive Design:

   • Refine Tailwind breakpoints in existing components
   • Ensure 44x44px touch targets
   • Test layouts at 320px, 768px, 1920px

4. Documentation:

   • Update README files with setup instructions
   • Create quickstart guide for reviewers

No new directories or major structural changes required.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

No violations detected - Complexity tracking not required.

This feature maintains existing architecture and focuses on polish/integration. All constitutional principles are satisfied without introducing additional complexity.

---

Post-Design Constitution Check

Re-evaluation after Phase 0 (Research) and Phase 1 (Design) completion

Design Artifacts Generated

1. research.md: 10 technical decisions documented

   • UI state management patterns (React hooks)
   • Loading/empty/error state designs
   • Responsive design breakpoints (Tailwind defaults)
   • Touch target sizing (44x44px minimum)
   • API client error handling (existing implementation)
   • Form validation patterns (existing implementation)
   • Optimistic UI updates
   • Environment configuration

2. data-model.md: Reference to existing entities

   • User (from Spec 2)
   • Task (from Spec 1)
   • AuthSession (frontend only)
   • No new entities introduced

3. contracts/existing-api-reference.yaml: OpenAPI 3.0 specification

   • Authentication endpoints (Spec 2)
   • Task CRUD endpoints (Spec 1)
   • No new endpoints introduced

4. quickstart.md: Testing and validation guide

   • Setup instructions (5 minutes)
   • Test scenarios for all 5 user stories
   • Common issues and solutions
   • Performance benchmarks
   • Validation checklist

Re-evaluation Results

Principle I: User-Centric Functionality ✅ PASS

• Research confirms focus on user feedback (loading, empty, error states)
• Responsive design ensures accessibility across devices
• No changes to core functionality

Principle II: Spec-Driven Development ✅ PASS

• All design artifacts generated via spec-driven workflow
• Research documents existing patterns and decisions
• No ad-hoc implementations

Principle III: Security & Data Privacy ✅ PASS

• No new security mechanisms introduced
• Reuses existing JWT authentication
• API client maintains Authorization header inclusion
• No changes to data isolation logic

Principle IV: Scalable Architecture ✅ PASS

• Maintains stateless architecture
• No new backend state introduced
• Responsive design scales across devices
• Centralized API client improves maintainability

Principle V: Maintainable & Consistent Code ✅ PASS

• Research documents consistent patterns (loading states, error handling)
• Tailwind CSS usage enforced
• Reusable component patterns identified
• No new complexity introduced

Key Standards Compliance (Post-Design)

API Compliance ✅ PASS

• OpenAPI specification documents all existing endpoints
• No new endpoints introduced
• Error handling patterns documented

Database Integrity ✅ PASS

• No database changes
• Existing schema maintained
• No new migrations required

Frontend Quality ✅ PASS

• Responsive design patterns documented
• Tailwind CSS usage confirmed
• Component enhancement patterns identified

Authentication ✅ PASS

• Existing Better Auth + JWT maintained
• No changes to authentication flow
• Token handling patterns documented

Spec Adherence ✅ PASS

• All design artifacts reference spec.md
• Implementation will reference plan.md, research.md, data-model.md
• No deviations from specification

Post-Design Verdict

Overall Verdict: ✅ APPROVED - All principles and standards remain satisfied after design phase

Confirmation: The design phase (research, data model, contracts, quickstart) confirms that this feature:

1. Introduces no new architectural complexity
2. Maintains all existing security mechanisms
3. Focuses entirely on UI polish and integration
4. Follows established patterns from Specs 1 & 2
5. Requires no database or backend changes

Ready for Task Generation: Proceed to /sp.tasks command to generate implementation tasks

---

Planning Summary

Artifacts Generated

Artifact	Status	Purpose
spec.md	✅ Complete	Feature specification with 5 user stories
plan.md	✅ Complete	This file - implementation plan
research.md	✅ Complete	10 technical decisions documented
data-model.md	✅ Complete	Reference to existing entities
contracts/existing-api-reference.yaml	✅ Complete	OpenAPI 3.0 specification
quickstart.md	✅ Complete	Testing and validation guide
checklists/requirements.md	✅ Complete	Specification validation (all passed)

Next Steps

1. Generate tasks.md: Run /sp.tasks command to create implementation tasks
2. Implement: Run /sp.implement command to execute tasks
3. Test: Follow quickstart.md to validate all user stories
4. Document: Update README files with any new patterns

Status: ✅ Planning complete - Ready for task generation