KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

fastapi-bigger-application

★ 107 Open GitHub ↗

Example of FastAPI bigger application

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# FastAPI Car Shop ERP

[![Coverage: 78%](https://img.shields.io/badge/coverage-78%25-brightgreen.svg)](https://raw.githubusercontent.com/skatesham/fastapi-bigger-application/master/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**

---

fastapi-bigger-application

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README