A production-ready fullstack template combining FastAPI (Python) and TypeScript for rapid AI prototype development. Designed for freelancers and AI entrepreneurs who need to quickly build and deploy professional applications with modern development practices.
- FastAPI Backend: High-performance Python API with automatic OpenAPI documentation
- TypeScript Frontend: Type-safe frontend with modern React setup
- AI-Ready: Pre-configured integrations for common AI services and tooling
- Developer Experience: Optimized for use with Cursor and other AI-powered development tools
- Production Quality: Complete with testing frameworks, CI/CD pipelines, and deployment options
- Docker Integration: Containerized development and deployment workflows
- Authentication System: JWT authentication with secure password hashing
- Email Integration: Password recovery and notification system
- Dark Mode Support: Modern UI with light/dark theme switching
- Database Migrations: Automatic schema management with Alembic
- FastAPI for high-performance API endpoints
- SQLModel for SQL database interactions (ORM)
- Pydantic for data validation
- PostgreSQL as the SQL database
- Alembic for database migrations
- Pytest for testing
- Poetry for dependency management
- TypeScript for type safety
- React with hooks for UI components
- Chakra UI for responsive, accessible components
- Vite for fast builds
- Automatically generated API client
- Jest and React Testing Library for testing
- Playwright for End-to-End testing
- pnpm for package management
- GitHub Actions for CI/CD
- Docker and Docker Compose
- Pre-commit hooks for code quality
- ESLint and Prettier for code formatting
- Cursor-optimized project structure
- Swagger UI for API documentation
- Traefik as reverse proxy / load balancer
- Python 3.10+
- Node.js 18+
- Docker and Docker Compose (optional but recommended)
- Git
# Clone the repository
git clone https://github.com/telepace/quick-forge-ai.git
cd quick-forge-ai
# Setup using the automatic script
./setup.sh
# Or manually:
# Backend setup
cd backend
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install poetry
poetry install
# Frontend setup
cd ../frontend
pnpm install
# Start development servers
docker-compose up # Starts everythingCreate a .env file in the root directory based on the provided .env.example. Important values to update:
# Generate secure secret keys with:
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Required security settings
SECRET_KEY=your-generated-secret-key
FIRST_SUPERUSER=admin@example.com
FIRST_SUPERUSER_PASSWORD=your-secure-password
POSTGRES_PASSWORD=your-db-password
# Optional email settings
SMTP_HOST=
SMTP_USER=
SMTP_PASSWORD=
EMAILS_FROM_EMAIL=info@example.com# Run backend tests
cd backend
pytest
# Run frontend tests
cd frontend
pnpm test
# Run end-to-end tests
cd e2e
pnpm testquick-forge-ai/
βββ .github/ # GitHub workflows and templates
βββ backend/ # FastAPI application
β βββ app/ # API code
β β βββ api/ # API endpoints
β β βββ core/ # Configuration
β β βββ db/ # Database models and config
β β βββ services/ # Business logic
β β βββ utils/ # Utility functions
β βββ tests/ # Backend tests
β βββ alembic/ # Database migrations
β βββ poetry.lock # Locked dependencies
β βββ pyproject.toml # Python project config
βββ frontend/ # TypeScript React application
β βββ src/ # Application code
β β βββ components/ # React components
β β βββ hooks/ # Custom React hooks
β β βββ pages/ # Page components
β β βββ services/ # API service integrations
β β βββ types/ # TypeScript types
β β βββ utils/ # Utility functions
β βββ tests/ # Frontend tests
β βββ package.json # npm package config
β βββ vite.config.ts # Vite configuration
βββ e2e/ # End-to-end tests with Playwright
βββ docker/ # Docker configuration
β βββ backend/ # Backend Dockerfile
β βββ frontend/ # Frontend Dockerfile
βββ docs/ # Documentation
βββ scripts/ # Utility scripts
βββ docker-compose.yml # Docker Compose configuration
βββ docker-compose.prod.yml # Production Docker Compose
βββ README.md # This file
# Build and run in production mode
docker-compose -f docker-compose.prod.yml up -dThe deployment includes:
- Automatic HTTPS certificate management via Traefik
- Production-optimized Docker images
- Database backup configuration
See the deployment documentation for detailed instructions on deploying to various platforms.
You can build and run the documentation website locally using Docker:
# Build and run documentation
docker-compose -f docker-compose.docs.yml up --buildThe documentation will be available at http://localhost:3000.
The documentation is automatically built and deployed when changes are pushed to the main branch. The GitHub Actions workflow handles:
- Building a Docker image for the documentation
- Pushing the image to Docker Hub and GitHub Container Registry
- Deploying the documentation to GitHub Pages
You can find the deployed documentation at: https://docs.your-domain.com
Documentation source files are located in the website/content directory. To add or update documentation:
- Create or modify markdown files in the appropriate directory
- Test your changes locally using the Docker setup
- Push your changes to a feature branch and create a pull request
- Once merged, the documentation will be automatically deployed
This template is optimized for use with Cursor:
- Open the project in Cursor
- Use AI code completion to navigate and modify code
- Leverage custom Cursor commands in the
.cursor/directory - Enjoy enhanced productivity with AI-powered development
QuickForge AI makes it simple to integrate various AI services:
- Pre-configured connectors for popular AI APIs
- Example implementations for common AI patterns
- Structured components for AI-powered features
- Helper utilities for handling AI-specific data flows
- Use feature branches for new features
- Write tests for all new code
- Run the pre-commit hooks before committing
- Follow the contribution guidelines
- Backend API documentation - Available when the backend is running
- Frontend component documentation - Available when the frontend is running
- Project architecture
- Development guides
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please see our contributing guidelines for details.
If you want to get updates from the template in the future:
# Add the template as a remote
git remote add template https://github.com/telepace/quick-forge-ai.git
# Pull changes (without auto-merge)
git pull --no-commit template main
# Review changes and commit
git merge --continue- FastAPI team for the amazing framework
- TypeScript team for type safety
- All open-source contributors whose work makes this possible
Built with β€οΈ for AI entrepreneurs and freelancers. Happy coding!
See the development guide for instructions on setting up the development environment.
- Linting: We use various linters to maintain code quality
- Spell Checking: We use typos for spell checking. The configuration is in
_typos.toml
Quick Forge AI supports two database deployment options:
- Direct PostgreSQL Deployment (Default): A PostgreSQL database is deployed alongside your application.
- Supabase Cloud Service: Connect to a Supabase PostgreSQL database instance.
The system automatically detects which database to use based on environment variables:
- If
SUPABASE_URLis set in your environment variables, the system will use Supabase - If
SUPABASE_URLis not set, the system will use direct PostgreSQL deployment
You can configure the database by setting the appropriate environment variables:
In your .env file, ensure these settings:
POSTGRES_SERVER=db
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DB=app
In your .env file, set:
SUPABASE_URL=postgresql://postgres:your-password@db.abcdefghijkl.supabase.co:5432/postgres
This project provides optimized scripts and Makefile targets for common development tasks.
make backend-install- Install backend dependenciesmake backend-run- Run backend locally with hot reloadmake backend-format- Format backend code with ruffmake backend-lint- Run linters (mypy, ruff) on backend codemake backend-test- Run all backend tests with coveragemake backend-test-specific- Run a specific backend testmake backend-coverage-report- Open the HTML coverage reportmake backend-prestart- Run backend prestart initializationmake backend-migration- Create a new database migrationmake backend-migrate- Run database migrationsmake backend-downgrade- Downgrade database to previous migrationmake backend-shell- Start a Python shell with app contextmake backend-db-shell- Connect to database with psql
make frontend-install- Install frontend dependenciesmake frontend-dev- Run frontend development servermake frontend-build- Build frontend for productionmake frontend-test- Run frontend testsmake frontend-lint- Run linters on frontend code
make docker-build-all- Build all Docker imagesmake docker-push-all- Build and push all Docker imagesmake docker-deploy- Deploy to Docker Swarmmake docker-test- Run tests in Dockermake docker-test-local- Run tests in local Docker environment
make generate-client- Generate OpenAPI client for frontendmake format- Format code in all componentsmake lint- Run linters on all componentsmake clean- Clean build artifacts