Initial commit: Production-ready MVP template with FastAPI and Next.js

Author: mzkarami

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install backend dependencies
+        run: |
+          pip install uv
+          uv pip install --system --from-requirements backend/pyproject.toml
+
+      - name: Run backend linters and tests
+        run: |
+          cd backend
+          pytest
+
+      - name: Set up Node.js and pnpm
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: frontend/pnpm-lock.yaml
+
+      - name: Install frontend dependencies
+        run: |
+          cd frontend
+          pnpm install --frozen-lockfile
+
+      - name: Run frontend linters and tests
+        run: |
+          cd frontend
+          pnpm lint

.gitignore

@@ -0,0 +1,37 @@
+# Environment Variables
+# Never commit .env files with secrets
+.env
+
+# Python
+__pycache__/
+*.py[oc]
+*.py[cod]
+.venv/
+venv/
+env/
+
+# Python Build & Test Artifacts
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+
+# Node.js
+# Ignore all node_modules directories
+**/node_modules
+
+# Frontend Build Artifacts
+# Next.js build output
+**/.next/
+
+# IDE & Editor Files
+.idea/
+.vscode/
+*.swp
+
+# OS Files
+.DS_Store
+Thumbs.db

README.md

@@ -0,0 +1,44 @@
+# MVP Template: FastAPI, React (Next.js), and Postgres
+
+This repository is a production-ready template for building a Minimum Viable Product (MVP). It provides a solid architectural foundation for a modern web application, allowing you to focus on building your product's unique features from day one.
+
+## Getting Started
+
+### Prerequisites
+
+1.  **Docker & Docker Compose:** [Install Docker](https://docs.docker.com/get-docker/).
+2.  **Node.js & pnpm:** [Install pnpm](https://pnpm.io/installation).
+3.  **Python:** The backend uses Python 3.12+.
+
+### 1. Generate Frontend Lockfile (Critical First Step)
+
+Before running the Docker build, you must generate the `pnpm-lock.yaml` file. This file is essential for ensuring reproducible builds inside and outside of Docker.
+
+Navigate to the frontend directory and run the install command:
+
+```sh
+cd frontend
+pnpm install
+cd ..
+```
+
+This will create the `pnpm-lock.yaml` file in the `frontend` directory. Commit this file to your repository.
+
+### 2. Set Up Environment Variables
+
+Copy the example environment file to create your local configuration:
+
+```sh
+cp example.env .env
+```
+
+### 3. Run the Application
+
+With the lockfile generated and the `.env` file in place, you can now build and run the entire stack:
+
+```sh
+docker-compose up --build
+```
+
+- **Backend API** will be available at `http://localhost:8000`
+- **Frontend App** will be available at `http://localhost:3000`

backend/Dockerfile

@@ -0,0 +1,48 @@
+# --- Builder Stage: Compile dependencies --- #
+FROM python:3.12-slim AS builder
+
+# Install uv, our package manager
+RUN pip install --no-cache-dir uv
+
+WORKDIR /app
+
+# Copy the dependency definition file
+COPY pyproject.toml ./
+
+# Compile pyproject.toml into a requirements.txt file
+# This creates a locked set of dependencies for production
+RUN uv pip compile pyproject.toml -o requirements.txt
+
+
+# --- Final Stage: Build the application image --- #
+FROM python:3.12-slim
+
+# Set environment variables for Python
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Install uv again in the final stage
+RUN pip install --no-cache-dir uv
+
+# Copy the compiled requirements.txt from the builder stage
+COPY --from=builder /app/requirements.txt .
+
+# Install the production dependencies using the locked requirements file
+# Using sync ensures the environment is exactly as specified
+RUN uv pip sync --system requirements.txt
+
+# Copy the application code into the container
+COPY ./app ./app
+
+# Create a non-root user for security
+RUN groupadd -r appgroup && useradd -r -g appgroup -d /home/appuser -m -s /bin/bash appuser
+RUN chown -R appuser:appgroup /app
+USER appuser
+
+# Expose the application port
+EXPOSE 8000
+
+# Command to run the FastAPI application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/alembic.ini

@@ -0,0 +1,48 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+script_location = %(here)s/alembic
+
+# template used to generate migration file names
+# file_template = %%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+prepend_sys_path = .
+
+# database URL
+s sqlalchemy.url = driver://user:pass@localhost/dbname
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

backend/alembic/env.py

@@ -0,0 +1,68 @@
+import os
+import sys
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+
+from alembic import context
+
+# Add the project root to the Python path
+PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+sys.path.insert(0, PROJECT_ROOT)
+
+# Import your models here so Alembic can see them
+# from app.models import YourModel  # Example
+from sqlmodel import SQLModel
+
+# This is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Set the database URL from an environment variable
+# This assumes you have a DATABASE_URL environment variable set.
+# You can also set it directly in alembic.ini
+config.set_main_option('sqlalchemy.url', os.environ.get('DATABASE_URL'))
+
+# Your model's MetaData object for 'autogenerate' support
+target_metadata = SQLModel.metadata
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection, target_metadata=target_metadata
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/alembic/versions/.gitkeep

@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+app = FastAPI(title="MVP Template Backend")
+
+@app.get("/api/v1/health", tags=["Health"])
+def health_check():
+    """Check if the API is running."""
+    return {"status": "ok"}

backend/app/__init__.py

@@ -0,0 +1,53 @@
+[project]
+name = "backend"
+version = "0.1.0"
+description = "A FastAPI backend for the MVP template."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115.12",
+    "authlib>=1.6.0",
+    "cryptography>=45.0.4",
+    "email-validator>=2.2.0",
+    "httpx>=0.28.1",
+    "itsdangerous>=2.2.0",
+    "passlib[bcrypt]>=1.7.4",
+    "psycopg2-binary>=2.9.10",
+    "pydantic-settings>=2.9.1",
+    "python-dotenv>=1.1.0",
+    "python-jose[cryptography]>=3.5.0",
+    "python-multipart>=0.0.20",
+    "sqlalchemy>=2.0.41",
+    "sqlmodel>=0.0.24",
+    "uvicorn[standard]>=0.34.3",
+    "alembic>=1.16.2",
+    "jinja2>=3.1.6"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+    "black>=23.0.0",
+    "mypy>=1.0.0",
+    "httpx>=0.28.1",
+    "debugpy>=1.8.1",
+    "pytest-cov>=6.2.1",
+    "pytest-env>=1.0.0",
+    "pytest-asyncio>=0.23.0"
+]
+
+[tool.setuptools.packages.find]
+include = ["app*"]
+exclude = ["alembic*"]
+
+[tool.pyright]
+include = ["app"]
+exclude = ["**/__pycache__", ".venv", "**/.*_cache", "alembic/versions"]
+
+[tool.coverage.run]
+source = ["app"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true