FastAPI Car Shop ERP

Professional REST API ERP system for car shop management built with FastAPI 0.133, SQLAlchemy 2.0, and modern Python patterns.

---

✨ Features

• 🚀 FastAPI 0.133.1 - Latest stable version with modern patterns
• 🗄️ SQLAlchemy 2.0.47 - Modern ORM with async support
• 🔐 Professional Security - JWT with core.security module
• 📊 Pydantic V2.12.5 - Modern data validation and serialization
• 🏗️ Clean Architecture - Professional structure with core modules
• 🧪 Comprehensive Testing - Tests separated from application code
• 📝 Auto Documentation - Swagger/OpenAPI with /docs
• 🔧 Professional Tooling - Black, isort, mypy, pytest, coverage
• 🎯 Dependency Injection - FastAPI Annotated patterns
• 📦 Modern Packaging - pyproject.toml with professional setup
• 🔒 Security Best Practices - passlib, bcrypt, secure JWT handling

---

🛠️ Tech Stack

• Framework: FastAPI 0.133.1
• Database: PostgreSQL with SQLAlchemy 2.0.47
• Configuration: Pydantic Settings V2
• Authentication: JWT with python-jose[cryptography]
• Validation: Pydantic V2.12.5 + Pydantic Settings 2.13.1
• Testing: pytest 9.0.2 + pytest-asyncio 1.3.0 + pytest-cov 7.0.0
• Code Quality: Black 26.1.0, isort 8.0.0, flake8 7.3.0, mypy 1.19.1
• Security: passlib[bcrypt] 1.7.4, python-multipart 0.0.6
• Database Tools: psycopg2-binary 2.9.0, alembic 1.12.0
• Documentation: Auto-generated Swagger/OpenAPI
• Architecture: Clean API structure with v1 versioning

---

🏗️ Project Structure

fastapi-bigger-application/
├── app/                    # Application source code
│   ├── src/
│   │   ├── api/           # API layer (v1)
│   │   │   ├── deps.py    # Dependencies injection
│   │   │   ├── converters/ # Response converters
│   │   │   └── v1/
│   │   │       └── endpoints/
│   │   ├── core/          # Core modules
│   │   │   ├── config.py  # Pydantic Settings
│   │   │   ├── database.py # Database setup
│   │   │   └── security.py # JWT & auth
│   │   ├── domain/        # Business logic
│   │   └── internal/      # Internal utilities
│   └── main.py           # Application entry point
├── tests/                # Test suite (external)
├── Dockerfile            # Docker container configuration
├── docker-compose.yml    # Docker Compose orchestration
├── docker-dev.sh         # Interactive development script
├── .dockerignore         # Docker build exclusions
├── pyproject.toml       # Modern Python packaging
├── requirements.txt     # Dependencies
├── setup.cfg            # Flake8 configuration
├── .coveragerc          # Coverage configuration
└── .env.example        # Environment template

---

🚀 Quick Start

🐳 Docker (Recommended - Automated)

The fastest way to get started is using Docker Compose:

# Clone and start everything automatically
git clone https://github.com/carshop/fastapi-erp.git
cd fastapi-erp
docker-compose up --build

🚀 Interactive Development Script

For an enhanced development experience, use our interactive script:

# Run the interactive development script
./docker-dev.sh

The script provides:

• 🚀 Auto-start services with health checks
• 📊 Service status monitoring
• 📋 Live logs viewing
• 🛑 Clean stop/reset options
• 🔗 Quick access URLs
• 🎨 Colored output and status indicators

That's it! 🎉 The application will be available at:

• API: http://localhost:8000
• Documentation: http://localhost:8000/docs
• Database Admin: http://localhost:9000 (Adminer)

Services included:

• FastAPI App (port 8000) - Main application
• PostgreSQL (port 5432) - Database with persistent data
• Adminer (port 9000) - Database management interface

Local Development

If you prefer to run locally:

Prerequisites

• Python 3.11+
• PostgreSQL 12+
• Docker & Docker Compose (optional)

Installation

# Clone the repository
git clone https://github.com/carshop/fastapi-erp.git
cd fastapi-erp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Start the application
uvicorn app.main:app --reload

Environment Configuration

Create .env file based on .env.example:

# Database
DATABASE_URL=postgresql://user:password@localhost/dbname

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

# Service Configuration
SERVICE_NAME=fastapi-car-shop-erp
SERVICE_VERSION=1.0.0
SERVICE_DESCRIPTION=Professional ERP system for car shop management
SERVICE_AUTHOR=Your Name

# Application
DEBUG=false
ENVIRONMENT=production

# CORS
ALLOWED_HOSTS=localhost,127.0.0.1,yourdomain.com

Note: All service information (name, version, description, author) is centralized in the configuration and automatically used by health/info endpoints.

---

📚 API Documentation

Once running, access:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=app --cov-report=html

# Run specific test
pytest tests/test_jwt.py -v

---

🔧 Development

Code Quality

# Format code
black app/ tests/
isort app/ tests/

# Lint
flake8 app/ tests/

# Type checking
mypy app/

# Security check
bandit -r app/

Database Migrations

# Create migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

# Downgrade
alembic downgrade -1

---

📦 Deployment

🐳 Docker (Recommended)

Quick Start - One Command Setup

# Clone and run everything automatically
git clone https://github.com/carshop/fastapi-erp.git
cd fastapi-erp
docker-compose up --build

Docker Services

The docker-compose.yml includes three services:

1. api - FastAPI Application

   • Port: 8000
   • Auto-reload with volume mounting
   • Health checks enabled
   • Depends on database

2. db - PostgreSQL Database

   • Port: 5432
   • Persistent data volume
   • Health checks for startup order
   • Credentials: skatesham:skatesham-github

3. adminer - Database Admin Interface

   • Port: 9000
   • Web-based database management
   • Connect to db service

Docker Commands

# Start all services
docker-compose up --build

# Start in background
docker-compose up -d --build

# View logs
docker-compose logs -f api

# Stop services
docker-compose down

# Stop and remove volumes
docker-compose down -v

# Rebuild specific service
docker-compose up --build api

# Access running container
docker-compose exec api bash

Environment Variables

The Docker setup automatically configures:

• DATABASE_URL=postgresql://skatesham:skatesham-github@db:5432/skatesham
• DEBUG=true (development mode)
• ENVIRONMENT=development

Production

# Install production dependencies
pip install -e .

# Run with Gunicorn (recommended for production)
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker

📊 API Endpoints

System & Health Monitoring

• GET /api/v1/system/health - Complete health check with database connectivity and pool status
• GET /api/v1/system/health/live - Kubernetes liveness probe (simple alive check)
• GET /api/v1/system/health/ready - Kubernetes readiness probe (database connectivity)
• GET /api/v1/system/info - Detailed service information and configuration
• GET /api/v1/ - API root endpoint with navigation links

Authentication

• POST /api/v1/auth/login/ - User login with OAuth2PasswordRequestForm
• POST /api/v1/auth/register/ - User registration with password hashing
• GET /api/v1/auth/me/ - Get current authenticated user info

Resources

• GET /api/v1/buyers/ - List buyers
• POST /api/v1/buyers/ - Create buyer
• GET /api/v1/cars/ - List cars
• POST /api/v1/cars/ - Create car
• GET /api/v1/sales/ - List sales
• POST /api/v1/sales/ - Create sale

Health Check Examples

Basic Health Check

curl http://localhost:8000/api/v1/system/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0",
  "service": "fastapi-car-shop-erp",
  "checks": {
    "database": {
      "status": "healthy",
      "message": "Database connection successful"
    },
    "database_pool": {
      "status": "healthy",
      "pool_size": 5,
      "checked_in": 5,
      "checked_out": 0,
      "overflow": 0
    }
  }
}

Service Information

curl http://localhost:8000/api/v1/system/info

Response:

{
  "service": {
    "name": "fastapi-car-shop-erp",
    "version": "1.0.0",
    "description": "Professional ERP system for car shop management",
    "author": "Sham Vinicius Fiorin"
  },
  "technology": {
    "framework": "FastAPI",
    "database": "PostgreSQL",
    "orm": "SQLAlchemy",
    "authentication": "JWT OAuth2"
  },
  "environment": {
    "debug": false,
    "database_configured": true,
    "secret_key_configured": true,
    "environment": "development"
  }
}

Kubernetes Integration

The health endpoints are designed for Kubernetes orchestration:

# Kubernetes Deployment Example
apiVersion: apps/v1
kind: Deployment
metadata:
  name: fastapi-erp
spec:
  template:
    spec:
      containers:
      - name: app
        image: fastapi-erp:latest
        ports:
        - containerPort: 8000
        livenessProbe:
          httpGet:
            path: /api/v1/system/health/live
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /api/v1/system/health/ready
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 5

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and code quality checks
5. Submit a pull request

---

Source Documentation

• FastAPI
• Bigger Application
• SQL
• Pagination
• Testing
• Pydantic
• SQL Relational Database SQLAlchemy by FastAPI
• SQLAlchemy 1.4
• FastAPI Full Stack Template
• FastAPI "Real world example app"

---

📄 License

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

---

Created by

Sham Vinicius Fiorin

Built with ❤️ using FastAPI and modern Python patterns

---