URL Lists Manager

Overview

A modern, secure, and fast FastAPI application for managing and sharing lists of URLs. Built with async/await, JWT authentication, and a beautiful responsive dark-themed interface.

What Was Fixed

1. Application Startup Issues

• ✅ Fixed UUID column definitions (SQLAlchemy v2.0 compatibility)
• ✅ Fixed Pydantic v2 schema validation (regex → pattern)
• ✅ Fixed module imports (relative → absolute imports)
• ✅ Fixed async session context manager in startup event
• ✅ Corrected database session initialization

2. Security Improvements

• ✅ Moved hardcoded secrets to environment variables (.env)
• ✅ Added CORS middleware with configurable origins
• ✅ Implemented JWT authentication with configurable token lifetime
• ✅ Added configuration management with pydantic-settings
• ✅ Proper password hashing with bcrypt
• ✅ Secure token-based API authentication

3. Frontend Modernization

• ✅ Converted static HTML files to Jinja2 templates
• ✅ Implemented dark Tailwind CSS theme (slate-900 base)
• ✅ Fully responsive design for mobile, tablet, and desktop
• ✅ Beautiful gradient effects and modern UI components
• ✅ Smooth animations and transitions
• ✅ Mobile-friendly navigation with hamburger menu
• ✅ Consistent design language across all pages

4. Code Organization

• ✅ Created modular config system
• ✅ Separated concerns: auth, database, models, schemas, routers
• ✅ Better error handling
• ✅ Improved code structure for scalability

Project Structure

urllists/
├── main.py                 # FastAPI app setup, routes, Jinja2 integration
├── auth.py                 # JWT authentication, user manager
├── database.py             # SQLAlchemy async setup, session management
├── models.py               # SQLAlchemy ORM models (User, URLList)
├── schemas.py              # Pydantic schemas for validation
├── config.py               # Environment configuration management
├── requirements.txt        # Python dependencies
├── .env                    # Environment variables (update for production!)
├── .env.example            # Example environment variables
│
├── routers/
│   ├── __init__.py
│   ├── auth.py            # Auth routes (login, register, logout)
│   ├── users.py           # User management (admin only)
│   └── url_lists.py       # URL list CRUD operations
│
├── static/
│   ├── output.css         # Compiled Tailwind CSS
│   ├── input.css          # Tailwind CSS source with custom components
│   ├── tailwind.config.js # Tailwind configuration
│   ├── js/
│   │   ├── auth.js        # Authentication utilities
│   │   └── api.js         # API helpers
│   └── templates/
│       ├── base.html      # Base template with layout & nav
│       ├── index.html     # Homepage
│       ├── login.html     # Login page
│       ├── register.html  # Registration page
│       └── dashboard.html # User dashboard
│
└── sql_app.db             # SQLite database (created automatically)

Features

User Management

• Secure Registration: Email-based signup with password validation
• JWT Authentication: Token-based API authentication
• User Roles: Support for superusers (admin) and regular users
• Email Verification: Token-based email verification system

URL List Management

• Create Lists: Organize URLs with custom names and unique slugs
• View Lists: Access your URL collections from the dashboard
• Edit Lists: Update names, slugs, and URLs anytime
• Delete Lists: Remove lists you no longer need
• Share Publicly: Generate public URLs for list sharing

Public URL Access

• Raw Text Format: Access URL lists as plain text (one per line)
• Unique Slugs: Custom, memorable URLs for each list
• No Auth Required: Public lists don't require authentication

API Documentation

• Swagger UI: Interactive API docs at /api/docs
• ReDoc: Alternative API documentation at /api/redoc
• FastAPI Auto-docs: Full API schema and examples

Technology Stack

Backend

• FastAPI: Modern, fast web framework
• SQLAlchemy 2.0: Async ORM with full type hints
• Pydantic v2: Data validation and serialization
• python-jose: JWT token handling
• passlib + bcrypt: Secure password hashing
• aiosqlite: Async SQLite driver

Frontend

• Jinja2: Server-side template rendering
• Tailwind CSS v4: Utility-first CSS framework
• Vanilla JavaScript: No heavy dependencies
• Responsive Design: Mobile-first approach

Getting Started

Installation

1. Clone and navigate to the project

   cd urllists
   

2. Create and activate virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Configure environment

   cp .env.example .env
   # Edit .env with your settings, especially SECRET_KEY for production!
   

Running the Application

Option 1: Development with hot reload

uvicorn main:app --reload

Option 2: Production mode

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

The application will be available at http://localhost:8000

Building Tailwind CSS

While developing, rebuild CSS on changes:

./tailwindcss -i ./static/input.css -o ./static/output.css --watch

Or build once:

./tailwindcss -i ./static/input.css -o ./static/output.css

Default Admin Account

On first run, a default admin account is created:

• Email: localadmin@example.com
• Password: AdminSuper123!

⚠️ IMPORTANT: Change this password or delete this account in production!

Environment Variables

Key variables in .env:

# JWT & Security
SECRET_KEY=your-super-secret-key-change-this-in-production
TOKEN_LIFETIME=3600  # Token valid for 1 hour

# Database
DATABASE_URL=sqlite+aiosqlite:///./sql_app.db

# App Info
APP_NAME=URL List Manager
DEBUG=true

# CORS
CORS_ORIGINS=["http://localhost:3000", "http://localhost:8000"]

API Endpoints

Authentication

• POST /api/auth/register - Create new account
• POST /api/auth/jwt/login - Login and get JWT token
• POST /api/auth/logout - Logout

URL Lists (requires authentication)

• GET /api/url-lists/ - Get all user's lists
• POST /api/url-lists/ - Create new list
• GET /api/url-lists/{list_id} - Get specific list
• PUT /api/url-lists/{list_id} - Update list
• DELETE /api/url-lists/{list_id} - Delete list

Public Access

• GET /list-read/{unique_slug} - Get list as plain text (no auth)

Security Considerations

Production Checklist

• Change SECRET_KEY in .env to a strong random string
• Delete default admin account or change its password
• Set DEBUG=false in .env
• Use PostgreSQL instead of SQLite for production
• Enable HTTPS/TLS in reverse proxy
• Set appropriate CORS origins
• Use environment-specific .env files
• Enable rate limiting for API endpoints
• Add CSRF protection for forms
• Regular security updates for dependencies

Current Security Features

✅ JWT token-based authentication
✅ Password hashing with bcrypt
✅ CORS protection
✅ Secure session management
✅ User role-based access control
✅ SQL injection prevention (SQLAlchemy ORM)

Design Features

Dark Theme

• Base: Slate-900 dark background
• Cards: Slate-800 with subtle borders
• Accents: Sky-600 for primary actions
• Text: Slate-100 for readability
• Transitions: Smooth 200ms transitions

Responsive Design

• Mobile First: Optimized for small screens
• Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px)
• Touch Friendly: Large buttons and spacious layout
• Hamburger Menu: Mobile navigation
• Grid System: Auto-responsive grid for lists

Troubleshooting

Port Already in Use

# Kill process using port 8000
lsof -ti:8000 | xargs kill -9

Database Issues

# Delete the database to reset
rm sql_app.db

# Restart the app to recreate
uvicorn main:app --reload

CSS Not Updating

# Rebuild Tailwind CSS
./tailwindcss -i ./static/input.css -o ./static/output.css

Authentication Issues

• Clear browser localStorage: localStorage.clear()
• Check token in browser DevTools Network tab
• Verify JWT token hasn't expired

Next Steps & Recommendations

1. Database: Migrate to PostgreSQL for production
2. Testing: Add pytest unit and integration tests
3. Logging: Implement structured logging with Python logging
4. Monitoring: Add application monitoring and error tracking
5. Email Verification: Complete email verification workflow
6. Rate Limiting: Add rate limiting to prevent abuse
7. Admin Panel: Build admin dashboard for user management
8. Backup: Implement automated database backups
9. Documentation: Generate API documentation
10. Docker: Create Dockerfile for containerization

License

This project is provided as-is for educational and personal use.

Support

For issues or questions, refer to the FastAPI, SQLAlchemy, and Tailwind documentation:

• FastAPI Docs
• SQLAlchemy ORM
• Tailwind CSS

---

Last Updated: November 30, 2025
Version: 0.2.0