Full-Stack Python Boilerplate

A production-ready full-stack application boilerplate with FastAPI backend and React+Vite frontend, featuring modern development practices, Docker containerization, and comprehensive tooling.

🚀 Features

Backend (FastAPI)

• ✅ Modern Python: Python 3.12+ with async/await patterns
• ✅ FastAPI Framework: High-performance async API with automatic OpenAPI docs
• ✅ Service Layer Architecture: Clean separation of concerns (routes → services → models)
• ✅ JWT Authentication: Ready-to-use authentication with JWT tokens
• ✅ SQLAlchemy ORM: Async SQLAlchemy 2.0+ with PostgreSQL
• ✅ Database Migrations: Alembic for schema migrations
• ✅ Testing: pytest with async support and example tests
• ✅ Package Management: UV for fast, reliable dependency management
• ✅ Code Quality: Ruff for linting and formatting

Frontend (React + Vite)

• ✅ React 18: Latest React with TypeScript
• ✅ Vite: Lightning-fast build tool with HMR
• ✅ TypeScript: Full type safety across the application
• ✅ React Router: Client-side routing
• ✅ Axios: HTTP client with interceptors
• ✅ Custom Hooks: Reusable API hooks with loading/error states
• ✅ Path Aliases: Clean imports with @ alias
• ✅ Package Management: pnpm for efficient dependency management

DevOps & Infrastructure

• ✅ Docker: Multi-stage builds for optimized images
• ✅ Docker Compose: Development and production configurations
• ✅ Hot Reload: Both backend and frontend support hot-reload in dev mode
• ✅ Nginx: Production-ready reverse proxy with SPA routing
• ✅ Makefile: Convenient commands for common operations
• ✅ Health Checks: Container health monitoring

📁 Project Structure

python-fullstack-boilerplate/
├── backend/                    # FastAPI backend
│   ├── app/
│   │   ├── api/               # API routes
│   │   │   └── v1/
│   │   │       ├── endpoints/ # Route handlers
│   │   │       └── router.py  # Route aggregation
│   │   ├── core/              # Core utilities
│   │   │   ├── dependencies.py
│   │   │   ├── exceptions.py
│   │   │   └── security.py    # JWT auth
│   │   ├── db/                # Database layer
│   │   │   ├── models.py      # SQLAlchemy models
│   │   │   └── session.py     # DB session config
│   │   ├── models/            # Pydantic schemas
│   │   ├── services/          # Business logic
│   │   ├── config.py          # Settings
│   │   └── main.py            # FastAPI app
│   ├── tests/                 # Backend tests
│   ├── Dockerfile
│   ├── pyproject.toml         # UV dependencies
│   └── .env.example
│
├── frontend/                  # React + Vite frontend
│   ├── src/
│   │   ├── components/        # React components
│   │   ├── hooks/             # Custom hooks
│   │   ├── pages/             # Page components
│   │   ├── services/          # API services
│   │   ├── types/             # TypeScript types
│   │   ├── utils/             # Utilities
│   │   ├── App.tsx            # Root component
│   │   └── main.tsx           # Entry point
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── package.json
│   └── .env.example
│
├── docker-compose.yml         # Development setup
├── docker-compose.prod.yml    # Production setup
├── Makefile                   # Helper commands
├── .gitignore
└── README.md

🛠️ Prerequisites

• Docker and Docker Compose (recommended for easiest setup)
• OR for local development:
  • Python 3.12+
  • Node.js 22+
  • PostgreSQL 16+
  • UV for Python
  • pnpm for Node.js

🚀 Quick Start

Using Docker (Recommended)

1. Clone the repository

   git clone <your-repo-url>
   cd python-fullstack-boilerplate

2. Start the development environment

   make dev
   # Or: docker-compose up

3. Access the applications

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs
   • Health Check: http://localhost:8000/health

Local Development (Without Docker)

Backend Setup

1. Install UV

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create virtual environment and install dependencies

   cd backend
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e .

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your database credentials

4. Start PostgreSQL (using Docker is easiest)

   docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16-alpine

5. Run the backend

   fastapi dev app/main.py

Frontend Setup

1. Install pnpm (if not already installed)

   npm install -g pnpm

2. Install dependencies

   cd frontend
   pnpm install

3. Set up environment variables

   cp .env.example .env

4. Start the development server

   pnpm dev

📝 Available Commands

Using Makefile

make help              # Show all available commands
make dev               # Start development environment
make build             # Build all containers
make up                # Start all services in detached mode
make down              # Stop all services
make logs              # View logs from all services
make logs-backend      # View backend logs only
make logs-frontend     # View frontend logs only
make clean             # Stop and remove all containers and volumes
make test              # Run backend tests
make backend-shell     # Open shell in backend container
make frontend-shell    # Open shell in frontend container
make db-shell          # Open PostgreSQL shell
make prod-build        # Build production containers
make prod-up           # Start production environment
make prod-down         # Stop production environment

Backend Commands

# Run tests
docker-compose exec backend pytest -v

# Run specific test file
docker-compose exec backend pytest tests/test_users.py -v

# Format code with ruff
docker-compose exec backend ruff format app/

# Lint code
docker-compose exec backend ruff check app/

# Create database migration
docker-compose exec backend alembic revision --autogenerate -m "description"

# Apply migrations
docker-compose exec backend alembic upgrade head

Frontend Commands

# Install dependencies
docker-compose exec frontend pnpm install

# Build for production
docker-compose exec frontend pnpm build

# Lint code
docker-compose exec frontend pnpm lint

# Preview production build
docker-compose exec frontend pnpm preview

🔧 Configuration

Backend Environment Variables

Create backend/.env from backend/.env.example:

PROJECT_NAME="FastAPI Backend"
DEBUG=True
DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/app
SECRET_KEY=your-secret-key-here  # Change in production!
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
CORS_ORIGINS=["http://localhost:5173","http://localhost:3000"]

Frontend Environment Variables

Create frontend/.env from frontend/.env.example:

VITE_API_URL=/api/v1

🧪 Testing

Backend Tests

The backend includes pytest tests with async support:

# Run all tests
make test

# Run with coverage
docker-compose exec backend pytest --cov=app tests/

# Run specific test
docker-compose exec backend pytest tests/test_users.py::test_create_user -v

Frontend Tests

Frontend testing structure is ready. Add tests using Vitest:

cd frontend
pnpm add -D vitest @testing-library/react @testing-library/jest-dom

📚 API Documentation

Once the backend is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Example Endpoints

Users

• POST /api/v1/users/register - Register new user
• POST /api/v1/users/login - Login and get JWT token
• GET /api/v1/users/ - List all users
• GET /api/v1/users/{id} - Get specific user
• DELETE /api/v1/users/{id} - Delete user

Items

• POST /api/v1/items/ - Create item
• GET /api/v1/items/ - List all items
• GET /api/v1/items/{id} - Get specific item
• PUT /api/v1/items/{id} - Update item
• DELETE /api/v1/items/{id} - Delete item

🚢 Production Deployment

Build Production Images

make prod-build

Deploy with Docker Compose

1. Create production environment file

   cp docker-compose.prod.yml .env.prod

2. Set production environment variables

   POSTGRES_USER=prod_user
   POSTGRES_PASSWORD=secure_password_here
   POSTGRES_DB=prod_db
   SECRET_KEY=very-secure-secret-key-here
   CORS_ORIGINS=["https://yourdomain.com"]

3. Start production services

   docker-compose -f docker-compose.prod.yml up -d

Production Checklist

• Change all default passwords
• Generate secure SECRET_KEY (use openssl rand -hex 32)
• Set DEBUG=False in backend
• Configure proper CORS origins
• Set up SSL/TLS certificates
• Configure database backups
• Set up monitoring and logging
• Configure firewall rules
• Use environment-specific .env files
• Review and update security headers in nginx

🏗️ Architecture

Backend Architecture

Request → FastAPI Router → Endpoint Handler → Service Layer → Database
                                ↓
                         Pydantic Validation
                                ↓
                         Response Serialization

Key Patterns:

• Service Layer: Business logic separated from routes
• Dependency Injection: FastAPI dependencies for database sessions, auth
• Async/Await: Fully async database operations
• Type Safety: Pydantic models for validation and serialization

Frontend Architecture

Component → Service → API Client → Backend API
     ↓
Custom Hook → State Management
     ↓
TypeScript Types

Key Patterns:

• Service Pattern: API calls abstracted in service files
• Custom Hooks: Reusable logic with useApi hook
• Type Safety: Full TypeScript coverage
• Axios Interceptors: Centralized auth and error handling

🔐 Authentication Flow

1. User registers via /api/v1/users/register
2. User logs in via /api/v1/users/login → receives JWT token
3. Frontend stores token in localStorage
4. Axios interceptor adds token to all requests
5. Backend validates token on protected routes

📦 Adding New Features

Adding a New Backend Endpoint

1. Create Pydantic model in backend/app/models/
2. Create SQLAlchemy model in backend/app/db/models.py
3. Create service in backend/app/services/
4. Create endpoint in backend/app/api/v1/endpoints/
5. Register router in backend/app/api/v1/router.py
6. Add tests in backend/tests/

Adding a New Frontend Page

1. Create TypeScript types in frontend/src/types/
2. Create service in frontend/src/services/
3. Create page component in frontend/src/pages/
4. Add route in frontend/src/App.tsx

🐛 Troubleshooting

Database Connection Issues

# Check if database is running
docker-compose ps db

# View database logs
docker-compose logs db

# Connect to database
make db-shell

Backend Not Starting

# View backend logs
make logs-backend

# Check if dependencies are installed
docker-compose exec backend pip list

Frontend Build Errors

# Clear node_modules and reinstall
docker-compose exec frontend rm -rf node_modules
docker-compose exec frontend pnpm install

# Check for TypeScript errors
docker-compose exec frontend pnpm build

Port Already in Use

If ports 5173, 8000, or 5432 are already in use, modify the port mappings in docker-compose.yml.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastAPI - Modern Python web framework
• React - UI library
• Vite - Build tool
• UV - Python package manager
• pnpm - Node.js package manager

📞 Support

For issues and questions:

• Open an issue on GitHub
• Check existing documentation
• Review the API docs at /docs

---

Happy Coding! 🚀