Metadata-Version: 2.4
Name: syeedalireza-flashcore
Version: 1.0.1
Summary: High-Concurrency Flash Sale Engine
Author-email: Alireza Aminzadeh <syeedalireza@yahoo.com>
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi==0.110.0
Requires-Dist: uvicorn[standard]==0.27.1
Requires-Dist: redis==5.0.3
Requires-Dist: pydantic==2.6.3
Requires-Dist: pydantic-settings==2.2.1
Requires-Dist: pytest==8.1.1
Requires-Dist: pytest-asyncio==0.23.5
Requires-Dist: pytest-cov==4.1.0
Requires-Dist: httpx==0.27.0

# FlashCore: High-Concurrency Flash Sale Engine

![Python](https://img.shields.io/badge/python-3.12-blue.svg)
![FastAPI](https://img.shields.io/badge/FastAPI-0.110.0-green.svg)
![Redis](https://img.shields.io/badge/redis-7.2-red.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

**FlashCore** is an enterprise-grade, high-concurrency drop engine designed to handle massive traffic spikes during flash sales. It guarantees zero overselling using atomic Redis Lua scripts and ensures eventual consistency with a PostgreSQL database.

Developed by **Alireza Aminzadeh** ([@syeedalireza](https://github.com/syeedalireza)).

## 🏗 Architecture & Design Patterns

- **Clean Architecture:** Strict separation of Domain, Application, and Infrastructure layers.
- **Event-Driven:** Uses Redis Pub/Sub (or Kafka in larger deployments) to decouple inventory reservation from order processing.
- **Atomic Operations:** Utilizes Redis Lua scripting to decrement inventory atomically, preventing race conditions during high traffic.
- **Zero-Trust Security:** Internal services (Redis, PostgreSQL) are strictly isolated within Docker networks and never exposed to the public internet.

## 🚀 Quick Start (Docker)

This project is fully containerized and optimized for both Windows (Docker Desktop) and Linux production environments.

1. **Clone the repository:**
   ```bash
   git clone https://github.com/syeedalireza/FlashCore.git
   cd FlashCore
   ```

2. **Environment Setup:**
   ```bash
   cp .env.example .env
   # Edit .env with your secure credentials
   ```

3. **Build and Run:**
   ```bash
   docker-compose up --build -d
   ```

4. **Access the API Documentation:**
   Open `http://localhost/docs` in your browser.

## 🛡 Security & DevOps Standards

- **Non-Root Containers:** The FastAPI application runs as a restricted user (UID 1000).
- **Resource Limits:** Strict CPU and Memory limits are enforced in `docker-compose.yml` to prevent host starvation.
- **Network Isolation:** Databases are not bound to `0.0.0.0`. Only the reverse proxy/API gateway is exposed.
- **Line Endings:** Enforced `LF` line endings via `.gitattributes` for seamless Windows-to-Linux deployment.

## 🧪 Testing

Run the comprehensive test suite (Unit & Integration):

```bash
docker-compose exec api pytest -v --cov=src
```

## 📜 License

This project is licensed under the MIT License.
