TodoFlow — Modern Full-Stack Task Management

A sophisticated, full-stack task management application featuring a Dark Professional SaaS UI with Framer Motion animations and glassmorphism effects.

🚀 Tech Stack Overview

Technology	Version	Purpose
Frontend Framework	Next.js 16+	Server-rendered React applications
Frontend Language	TypeScript 5.0+	Type-safe JavaScript development
Backend Framework	FastAPI	High-performance Python web framework
Backend Language	Python 3.11+	Modern backend development
ORM	SQLModel	SQL databases with Pydantic + SQLAlchemy
Database	Neon Serverless PostgreSQL	Cloud-native PostgreSQL with serverless scaling
Authentication	Better Auth	Secure user authentication
Styling	Tailwind CSS + Framer Motion	Rapid UI development with animations
Security	JWT Manual Signing	Secure token-based authentication

🔐 Secure JWT Bridge Architecture

TodoFlow implements a sophisticated Secure JWT Bridge that enables seamless authentication between the Next.js frontend and FastAPI backend:

How It Works:

1. Frontend Authentication: Better Auth handles user authentication and session management
2. Server-Side Token Signing: The Next.js server component manually signs JWT tokens using jose library
3. Backend Verification: FastAPI backend verifies JWT tokens using the same shared secret (BETTER_AUTH_SECRET)
4. Secure Communication: All API requests include the signed JWT in the Authorization header

Key Features:

• Manual JWT Signing: Next.js server component signs tokens with user session data
• Shared Secret: Both frontend and backend use the same BETTER_AUTH_SECRET for signing/verification
• Secure Transmission: Tokens are passed securely from server to client components
• 24-hour Expiration: Automatic token expiration for enhanced security

📁 Project Structure

todo-full-stack-web-application/
├── backend/                    # FastAPI backend service
│   ├── src/
│   │   ├── main.py            # FastAPI application entry point
│   │   ├── auth_utils.py      # JWT verification utilities
│   │   ├── dependencies.py    # Authentication dependencies
│   │   ├── db.py              # Database connection management
│   │   └── models/
│   │       └── task.py        # SQLModel task definitions
│   └── requirements.txt       # Python dependencies
├── frontend/                   # Next.js frontend application
│   ├── src/
│   │   ├── app/               # Next.js App Router pages
│   │   │   ├── dashboard/     # Protected dashboard route
│   │   │   ├── login/         # Login page
│   │   │   └── signup/        # Signup page
│   │   ├── components/        # Reusable UI components
│   │   ├── lib/
│   │   │   ├── auth.ts        # Better Auth configuration
│   │   │   ├── auth-client.ts # Client-side auth utilities
│   │   │   └── api.ts         # API client with JWT integration
│   │   └── services/          # Service layer (if any)
│   ├── package.json           # Node.js dependencies
│   └── next.config.js         # Next.js configuration
├── .env.example               # Environment variables template
├── README.md                  # This file
└── CLAUDE.md                  # Development guidelines

⚙️ Setup Instructions

Prerequisites

• Node.js 18+ (for frontend)
• Python 3.11+ (for backend)
• PostgreSQL database (Neon recommended)

1. Clone and Navigate

git clone <repository-url>
cd todo-full-stack-web-application

2. Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

# Configure environment variables
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:8000
DATABASE_URL=<your_postgresql_connection_string>
BETTER_AUTH_SECRET=<your_secret_key_min_32_chars>
BETTER_AUTH_URL=http://localhost:3000

3. Backend Setup

# Navigate to backend directory
cd ../backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies (if requirements.txt exists)
pip install fastapi uvicorn python-jose[cryptography] sqlmodel psycopg2-binary python-dotenv python-multipart

# Copy environment template
cp .env.example .env

# Configure environment variables
DATABASE_URL=<your_postgresql_connection_string>
BETTER_AUTH_SECRET=<same_secret_as_frontend_min_32_chars>

4. Start Applications

Start Backend:

cd backend
uvicorn src.main:app --reload --port 8000

Start Frontend:

cd frontend
npm run dev

5. Access Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• Backend Docs: http://localhost:8000/docs

🛡️ Security Features

• JWT Token Security: Industry-standard JSON Web Token implementation
• Secret Sharing: Secure shared secret between frontend and backend
• Session Management: Proper session handling with Better Auth
• Database Security: Encrypted PostgreSQL connections
• Input Validation: Comprehensive validation on both frontend and backend
• CORS Configuration: Proper cross-origin resource sharing settings

🎨 UI/UX Highlights

• Dark Professional Theme: Modern SaaS-style dark interface
• Framer Motion Animations: Smooth, engaging user interactions
• Glassmorphism Effects: Contemporary UI elements with frosted glass effect
• Responsive Design: Fully responsive across all device sizes
• Intuitive Task Management: Clean, organized task interface

🚀 Deployment

Frontend Deployment

• Vercel (recommended for Next.js)
• Netlify, AWS Amplify, or other static hosting providers

Backend Deployment

• Railway, Render, or other Python hosting platforms
• Docker containerization supported

---

Built with ❤️ using modern full-stack technologies

© 2025 TodoFlow - Secure, Scalable Task Management