Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/skatesham/fastapi-bigger-application

Example of FastAPI bigger application
https://github.com/skatesham/fastapi-bigger-application

docker-compose fastapi postgresql python rest-api

Last synced: about 9 hours ago
JSON representation

Example of FastAPI bigger application

Awesome Lists containing this project

README 

          
# FastAPI Car Shop ERP



[![Coverage: 78%](https://img.shields.io/badge/coverage-78%25-brightgreen.svg)](tests/)

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

[![FastAPI](https://img.shields.io/badge/FastAPI-0.133.1-green.svg)](https://fastapi.tiangolo.com/)

[![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2.0.47-blue.svg)](https://www.sqlalchemy.org/)

[![Pydantic](https://img.shields.io/badge/Pydantic-2.12.5-orange.svg)](https://docs.pydantic.dev/)



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:



```bash

# 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:



```bash

# 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



```bash

# 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`:



```bash

# 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



```bash

# 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



```bash

# Format code

black app/ tests/

isort app/ tests/



# Lint

flake8 app/ tests/



# Type checking

mypy app/



# Security check

bandit -r app/

```



### Database Migrations



```bash

# Create migration

alembic revision --autogenerate -m "Description"



# Apply migrations

alembic upgrade head



# Downgrade

alembic downgrade -1

```



---



## 📦 Deployment



### 🐳 Docker (Recommended)



#### Quick Start - One Command Setup



```bash

# 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



```bash

# 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



```bash

# 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

```bash

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

```



Response:

```json

{

  "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

```bash

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

```



Response:

```json

{

  "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:



```yaml

# 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](https://fastapi.tiangolo.com/)

- [Bigger Application](https://fastapi.tiangolo.com/tutorial/bigger-applications/)

- [SQL](https://fastapi.tiangolo.com/tutorial/sql-databases/)

- [Pagination](https://uriyyo-fastapi-pagination.netlify.app/)

- [Testing](https://fastapi.tiangolo.com/tutorial/testing/)  

- [Pydantic](https://pydantic-docs.helpmanual.io/)  

- [SQL Relational Database SQLAlchemy by FastAPI](https://fastapi.tiangolo.com/tutorial/sql-databases/?h=databa#sql-relational-databases)

- [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/tutorial/engine.html)  

- [FastAPI Full Stack Template](https://github.com/fastapi/full-stack-fastapi-template)

- [FastAPI "Real world example app"](https://github.com/nsidnev/fastapi-realworld-example-app)



---



## 📄 License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.



---



## Created by

> Sham Vinicius Fiorin



**Built with ❤️ using FastAPI and modern Python patterns**



---