template-fastapi-vue-clean-arch
Starter template · Python 3.12 · Vue 3 · MIT

A FastAPI and Vue starter with strict domain boundaries.

A production-style full-stack skeleton for new projects: an async FastAPI backend with Pydantic v2 validation, a strict TypeScript Vue 3 client and PostgreSQL, with specifications and decision records in the repository from the first commit.

Use this template Run it locally
  • FastAPI + Pydantic v2
  • SQLAlchemy 2.0 async
  • Vue 3 + strict TypeScript
  • PostgreSQL 16 or SQLite

From browser to database, one direction

A request crosses the gateway and the application layer, which drive the domain and reach the database only through the repository. Business invariants live in the domain, not in the endpoints.

Request flow through the FastAPI template The Vue client calls the FastAPI gateway, which calls the application layer. The application layer uses the domain core and the infrastructure repository, and the repository reaches PostgreSQL or SQLite through an async driver. Vue 3 client TypeScript · Vite FastAPI gateway Pydantic v2 · ProblemDetails Application Use cases · DTOs Domain core Entities · invariants Infrastructure SQLAlchemy async repository Database PostgreSQL 16 or SQLite

What is in the box

Backend

Python 3.12 and FastAPI

Pydantic v2 models, SQLAlchemy 2.0 with an async session, served by Uvicorn. Swagger docs at /docs and a health endpoint at /api/v1/health.

Frontend

Vue 3 and TypeScript

Composition API, strict TypeScript and Vite, with plain CSS and the NainDev suite bar for navigation.

Data

PostgreSQL or SQLite

PostgreSQL 16 for production. A SQLite async driver gives zero-dependency local development.

Governance

Specs and decisions

EARS requirements in docs/10-requirements.md and an ADR for the architecture. CI uses the shared reusable workflows.

Run it in a minute

Docker Compose starts the whole stack. The backend also runs on its own, with no Docker.

Full stack with Docker Compose

docker compose up --build
# client   http://localhost:5173
# API docs http://localhost:8000/docs
# health   http://localhost:8000/api/v1/health

Backend only

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Tests and checks

cd backend
python -m pytest tests -v

cd frontend
npm install
npx tsc --noEmit
npm run build

Deploy on free tiers

Free serverless PostgreSQL on Neon or Supabase, the container on Render or Fly.io, and the static client on Cloudflare Pages or GitHub Pages.