Full Stack FastAPI Template (Refactored)

Note: This project is a comprehensive architectural refactoring of the original project fastapi/full-stack-fastapi-template.

The main goal of this fork is to evolve the original template into an opinionated, production-ready boilerplate, showcasing modern best practices for both backend and frontend development. The focus has shifted from a simple template to a robust foundation with a clean, scalable, and testable architecture.

About this Project

This project is designed as a learning resource and a high-quality starting point for new applications. Key philosophies include:

• Explicit is better than implicit: Dependencies, configurations, and data flows are clearly defined.
• Clean Architecture: Clear separation of concerns between layers (presentation, business logic, data access).
• Modern Best Practices: Utilization of the latest stable features from FastAPI, React, and their respective ecosystems.

Key Architectural Decisions

This project implements several key patterns that define its structure:

Backend

• Layered Architecture: The code is strictly separated into layers: routes (presentation), deps (dependency management), crud (data access), and core (business logic and configuration).
• Object-Oriented Design: The entire backend is rewritten using classes (AppFactory, class-based views, provider classes, repositories) to improve encapsulation, reusability, and testability.
• Explicit Dependency Management: A central deps.py module defines all FastAPI dependencies as "callable" provider classes, ensuring consistency and clean, predictable code.
• Repository Pattern: Database operations are encapsulated in CRUD classes, abstracting away the data access logic from the business logic.

Frontend

• Component-Driven Architecture: The UI is built using a feature-based structure. A clear distinction is made between reusable UI primitives (/components/ui) and feature-specific components (/components).
• Centralized State Management: Server state is exclusively managed by TanStack Query, which acts as a single source of truth for all API data, handling caching, refetching, and synchronization.
• The "Action-Dialog" Pattern: A standardized pattern for components that trigger actions in a dialog (e.g., Edit, Delete), separating the Trigger from the Dialog to ensure a clean, unidirectional data flow.

Technology Stack

• ⚡ FastAPI for the Python backend API.
  • 🧰 SQLModel for Python SQL database interactions (ORM).
  • 🔍 Pydantic for data validation and settings management.
  • 💾 PostgreSQL as the SQL database.
• 🚀 React for the frontend.
  • ✨ TypeScript for robust type safety.
  • ⚛️ TanStack Query & TanStack Router for state management and routing.
  • 🎨 Chakra UI for the component library.
  • 🤖 An automatically generated API client via openapi-ts.
  • 🦇 Dark mode support.
• 🔑 JWT (JSON Web Token) authentication with email-based password recovery.
• ✅ Unit tests with Pytest and Vitest.

Screenshots

The UI functionality remains the same as in the original project.

Login	Admin Dashboard

Create User	Items List

User Settings	Dark Mode

Quick Start (Local Development)

This project is designed to be run locally without Docker.

1. Backend

• Navigate to the backend/ directory.
• Create and configure your .env file from .env.example.
• Install dependencies: pip install -r requirements.txt.
• Run initial database creation: python src/app/initial_data.py.
• Run the server: uvicorn app.main:app --reload.

(For detailed instructions, see the Backend README).

2. Frontend

• Navigate to the frontend/ directory.
• Create and configure your .env file from .env.example.
• Install dependencies: npm install.
• Generate the API client: npm run generate-client.
• Run the development server: npm run dev.

(For detailed instructions, see the Frontend README).

License

This project is licensed under the terms of the MIT license.