🚀 FasCraft - FastAPI Project Generator

Build production-ready FastAPI applications with enterprise-grade features in seconds.

FasCraft is a powerful CLI tool that generates production-ready FastAPI projects with domain-driven architecture, comprehensive error handling, and enterprise-grade features. Stop writing boilerplate code and start building amazing APIs!

✨ Features

🏗️ Project Generation

• Interactive project creation with guided setup and dry-run mode
• Domain-driven architecture ready for module generation
• Essential project structure with configuration and routing
• Automatic backup & rollback for safe operations
• Graceful degradation with fallback templates

🔧 Advanced Management

• Project analysis with recommendations and health checks
• Legacy migration to domain-driven architecture
• Configuration management with TOML support
• Module generation with multiple template types
• Safe module removal with automatic updates

🛡️ Enterprise Features

• Comprehensive error handling with actionable suggestions
• Input validation & sanitization for security
• File system permission checking
• Disk space validation
• Network path validation
• Windows reserved name protection

🎨 Developer Experience

• Rich console output with progress tracking
• Colored error messages with recovery guidance
• Interactive mode for guided project creation
• Dry-run mode to preview changes
• Cross-platform compatibility (Windows, macOS, Linux)

🚀 Quick Start

Installation

# Using pip
pip install fascraft

# Using Poetry
poetry add fascraft

# From source
git clone https://github.com/yourusername/fascraft.git
cd fascraft
pip install -e .

Create Your First Project

# Generate a new FastAPI project (interactive mode)
fascraft new

# Or specify project name directly
fascraft new my-awesome-api

# Preview changes without applying them
fascraft new my-awesome-api --dry-run

# Navigate to project
cd my-awesome-api

# Install dependencies
pip install -r requirements.txt

# Run the application
uvicorn main:app --reload

That's it! Your FastAPI application is now running at http://localhost:8000 🎉

📚 Complete Workflow Example

1. Create a New Project

fascraft new ecommerce-api
cd ecommerce-api

2. Generate Domain Modules

# Create user management module
fascraft generate users

# Create product catalog module
fascraft generate products

# Create order management module
fascraft generate orders

3. List and Manage Modules

# See all modules with health status
fascraft list

# Update module templates
fascraft update users

# Remove a module safely
fascraft remove products

4. Analyze and Optimize

# Get project analysis and recommendations
fascraft analyze

# Migrate legacy projects to domain-driven architecture
fascraft migrate ../old-project

# Manage project configuration
fascraft config show

🛠️ Available Commands

Core Commands

Command	Description	Example
new	Create new FastAPI project	fascraft new my-api
generate	Generate domain module	fascraft generate users
list	List all modules	fascraft list
remove	Remove module safely	fascraft remove users
update	Update module templates	fascraft update users

Advanced Commands

Command	Description	Example
analyze	Analyze project structure	fascraft analyze
migrate	Migrate legacy projects	fascraft migrate ../old
config	Manage configuration	fascraft config show
environment	Manage environments	fascraft environment init
dockerize	Add Docker support	fascraft dockerize
ci-cd	Add CI/CD support	fascraft ci-cd add
deploy	Generate deployment files	fascraft deploy generate

Utility Commands

Command	Description	Example
dependencies	Manage module dependencies	fascraft dependencies show
docs	Generate documentation	fascraft docs generate
test	Generate test files	fascraft test users
list-templates	List available templates	fascraft list-templates
hello	Say hello	fascraft hello World
version	Show version	fascraft version
--help	Show help	fascraft --help

🏗️ Generated Project Structure

my-awesome-api/
├── 📁 config/                 # Configuration management
│   ├── __init__.py
│   ├── settings.py           # App settings with Pydantic
│   ├── database.py           # Database configuration
│   ├── exceptions.py         # Custom exceptions
│   └── middleware.py         # FastAPI middleware
├── 📁 routers/               # API routing
│   ├── __init__.py
│   └── base.py              # Base router with health checks
├── 📄 main.py                # FastAPI application
├── 📄 pyproject.toml         # Poetry configuration
├── 📄 requirements.txt       # Production dependencies
├── 📄 requirements.dev.txt   # Development dependencies
├── 📄 requirements.prod.txt  # Production dependencies
├── 📄 .env                   # Environment variables
├── 📄 .env.sample           # Environment template
├── 📄 .gitignore            # Git ignore patterns
├── 📄 README.md             # Project documentation
└── 📄 fascraft.toml         # FasCraft configuration

🔧 Configuration Management

Project Configuration (fascraft.toml)

[project]
name = "my-awesome-api"
version = "0.1.0"
description = "A FastAPI project generated with FasCraft"

[router]
base_prefix = "/api/v1"
health_endpoint = true

[database]
default = "sqlite"
supported = ["sqlite", "postgresql", "mysql", "mongodb"]

[modules]
auto_import = true
prefix_strategy = "plural"
test_coverage = true

Environment Configuration (.env)

# Database Configuration
DATABASE_URL=sqlite:///./my-awesome-api.db

# Security
SECRET_KEY=your-secret-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=30

# CORS
CORS_ORIGINS=["*"]
CORS_ALLOW_CREDENTIALS=true

🚀 Advanced Features

Interactive Mode

FasCraft provides an interactive, guided experience for project creation:

# Start interactive mode
fascraft new

# Follow the guided prompts:
# 1. Enter project name
# 2. Choose project path
# 3. Select project type
# 4. Choose features to include
# 5. Confirm and create

Dry-Run Mode

Preview all changes before applying them:

# See what will be created without making changes
fascraft new my-api --dry-run

# Review project structure, files, and content
# Perfect for understanding what FasCraft will generate

Automatic Backup & Rollback

FasCraft automatically creates backups before destructive operations and provides rollback functionality if anything goes wrong.

# FasCraft automatically creates a backup
fascraft migrate ../legacy-project

# If migration fails, rollback is automatic
# Your original project is safe!

Comprehensive Error Handling

Every error includes actionable suggestions and recovery guidance.

# Clear error messages with solutions
❌ Error: Project 'test' already exists at ./test
💡 Suggestion: Use a different project name or remove the existing directory

Environment Management

FasCraft provides comprehensive environment management for multi-environment deployments:

# Initialize environment management
fascraft environment init --environments "dev,staging,prod"

# Switch between environments
fascraft environment switch --environment dev
fascraft environment switch --environment prod

# Validate configurations
fascraft environment validate

# List all environments
fascraft environment list-envs

Features:

• 🌍 Multi-environment support (dev, staging, prod, testing)
• 🔄 Seamless environment switching
• ✅ Configuration validation
• 📝 Environment-specific settings
• 🏗️ Enhanced configuration management

Cross-Platform Compatibility

Tested and verified on:

• ✅ Windows 10/11 (PowerShell, CMD)
• ✅ macOS 12+ (Terminal, bash, zsh)
• ✅ Linux (Ubuntu, CentOS, RHEL)

📖 API Endpoints

Health Check

GET /api/v1/health

Response:

{
  "status": "healthy",
  "version": "0.1.0"
}

Root Endpoint

GET /

Response:

{
  "message": "Hello from my-awesome-api!"
}

🧪 Testing

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=fascraft

# Run specific test file
pytest tests/test_new_command.py

Test Coverage

FasCraft maintains comprehensive test coverage with 18 test files covering:

• ✅ CLI command functionality
• ✅ Template rendering
• ✅ Error handling
• ✅ Validation systems
• ✅ Integration scenarios

🔒 Security Features

Input Validation

• Project name sanitization - Prevents malicious input
• Path validation - Protects against path traversal attacks
• Character filtering - Removes unsafe characters
• Length limits - Prevents buffer overflow attacks

File System Security

• Permission checking - Validates write access
• Disk space validation - Prevents disk exhaustion
• Network path validation - Secure remote operations

Dependency Security

• Bandit integration - Security vulnerability scanning
• Safety checks - Dependency vulnerability detection
• Version pinning - Secure dependency versions

🚀 Deployment

Development

# Install development dependencies
pip install -r requirements.dev.txt

# Run with auto-reload
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Production

# Install production dependencies
pip install -r requirements.prod.txt

# Run with Gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

Docker Support

# Add Docker support to existing project
fascraft dockerize

# This generates:
# - Dockerfile
# - docker-compose.yml
# - .dockerignore
# - Database initialization scripts

🛠️ Development

Prerequisites

• Python 3.10+
• Poetry (recommended) or pip
• Git

Setup Development Environment

# Clone repository
git clone https://github.com/yourusername/fascraft.git
cd fascraft

# Install dependencies
poetry install

# Install pre-commit hooks
pre-commit install

# Run tests
poetry run pytest

Code Quality Tools

• Black - Code formatting
• Ruff - Linting and import sorting
• isort - Import organization
• Bandit - Security scanning
• Safety - Dependency vulnerability checks

📚 Documentation

Getting Started

• 📖 Documentation Overview - Navigate all documentation
• 🚀 Quick Start Guide - Get up and running in minutes

User Guides

• 🏗️ Project Generation - Create new FastAPI projects
• 🔧 Module Management - Add and manage project modules
• ⚙️ Configuration - Manage application settings
• 🔄 Migrations - Database schema changes

Troubleshooting & Support

• 🔧 Troubleshooting Guide - Solve common issues
• 🤝 Community Support - Get help and contribute

Deployment & Production

• 🐳 Docker Integration - Containerize applications
• 🚀 CI/CD Integration - Automated workflows
• 🌍 Environment Management - Manage environments
• ✅ Production Ready - Production checklist

Developer Resources

• 💻 Contributing Guidelines - How to contribute
• 🧪 Testing Guide - Testing strategies
• ⚠️ Error Handling - Error handling patterns

Examples

• Basic API - Simple CRUD operations
• E-commerce API - Business logic examples
• Authentication API - Security and user management
• Database Integration - ORM and database patterns

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Fork and clone
git clone https://github.com/yourusername/fascraft.git
cd fascraft

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
poetry run pytest

# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# Create pull request

Code Standards

• Follow PEP 8 style guidelines
• Use type hints for all functions
• Write comprehensive docstrings
• Maintain test coverage above 80%
• Run all quality checks before committing

📄 License

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

🙏 Acknowledgments

• FastAPI - The amazing web framework that makes this possible
• Typer - CLI framework for building great command-line interfaces
• Rich - Rich text and beautiful formatting in the terminal
• Jinja2 - Template engine for code generation
• Pydantic - Data validation using Python type annotations

📞 Support

Getting Help

• 📖 Documentation - Comprehensive guides and tutorials
• 🐛 Issue Tracker - Report bugs and request features
• 💬 Discussions - Community Q&A
• 📧 Email Support - Direct support

Community

• 🌐 Website - Project website and resources
• 🐦 Twitter - Updates and announcements
• 💻 Discord - Real-time community support
• 📺 YouTube - Video tutorials and demos

---

Made with ❤️ by the FasCraft Team

FasCraft - Building better FastAPI projects, one command at a time! 🚀