stacking-pr 0.1.0

A FastAPI application for task management with database integration

Stacked PR FastAPI Task Tracker

A clean, professional-grade backend project built with FastAPI, Docker, PostgreSQL, and SQLAlchemy.

Built in a stacked PR workflow, step-by-step, from in-memory to production-ready DB logic.

Stacked PR Structure • Tech Stack • Testing • Usage • API • CI/CD

---

🌟 Stacked PRs

This repo is structured into clearly defined Pull Requests:

1. feat: add Task schema and in-memory task endpoints
2. feat: integrate PostgreSQL with SQLAlchemy and Alembic
3. feat: replace in-memory task store with PostgreSQL CRUD

Each PR builds cleanly on top of the previous, keeping history modular and understandable.

---

🚀 Tech Stack

• FastAPI: Web framework
• SQLAlchemy: ORM for PostgreSQL
• Alembic: Schema migrations
• Docker + Compose: Containerized dev environment
• PostgreSQL: Relational database
• Pytest: Testing framework with coverage
• GitHub Actions: CI/CD pipeline
• Black/isort/flake8: Code formatting and linting

---

📃 Project Structure

stacking_pr/
├── app/                   # Main application package
│   ├── __init__.py       
│   ├── main.py           # FastAPI app and entrypoint
│   ├── db.py             # Database engine/session
│   ├── dependencies.py   # FastAPI dependencies
│   ├── api/              # API routers
│   │   └── task_router.py
│   ├── models/           # SQLAlchemy models
│   │   └── task.py
│   └── schemas/          # Pydantic schemas
│       └── task.py
├── tests/                # Test suite
│   ├── __init__.py
│   ├── conftest.py       # Shared test fixtures
│   ├── test_main.py      # Main app tests
│   ├── api/              # API endpoint tests
│   ├── models/           # Model tests
│   ├── schemas/          # Schema validation tests
│   └── integration/      # Integration tests
├── alembic/              # Database migrations
├── .github/
│   └── workflows/        # CI/CD pipelines
├── alembic.ini           # Alembic configuration
├── docker-compose.yml    # Docker services
├── Dockerfile            # App containerization
├── pyproject.toml        # Project metadata & config
├── requirements.txt      # Python dependencies
├── Makefile              # Development commands
└── README.md             # Project documentation

---

🚧 Usage

⚡ Run Locally

git clone https://github.com/yourname/stacking_pr.git
cd stacking_pr

# Build and run containers
make docker

# Run alembic migrations
make migrate

# Follow logs
make logs

Open browser:

http://localhost:8000/docs

To stop:

make docker-down

---

📊 API

Create a Task

POST /tasks
Content-Type: application/json

{
  "id": 1,
  "title": "Stacked PRs FTW!",
  "is_completed": false
}

Get All Tasks

GET /tasks

---

🧪 Testing

Running Tests

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

# Run all tests
make test

# Run tests with coverage report
make test-cov

# Run specific test file
make test-file

# Run tests matching a pattern
make test-pattern

Test Structure

• Unit Tests: Individual component testing
• API Tests: FastAPI endpoint testing with TestClient
• Model Tests: SQLAlchemy model validation
• Schema Tests: Pydantic schema validation
• Integration Tests: End-to-end workflow testing

Coverage

Tests maintain 80% minimum coverage with HTML reports generated in htmlcov/.

---

📄 Makefile Commands

make setup         # Create virtual environment and install dependencies
make install       # Install requirements into venv
make run          # Run FastAPI locally (development)
make test         # Run pytest test suite
make test-cov     # Run tests with coverage report
make test-file    # Run specific test file
make test-pattern # Run tests matching a pattern
make docker       # Start Docker containers
make docker-down  # Stop and remove containers
make migrate      # Run alembic migrations
make logs         # Follow Docker logs
make clean        # Delete venv + __pycache__
make help         # Show all available commands

---

🚀 CI/CD Pipeline

GitHub Actions Workflow

The project includes a comprehensive CI/CD pipeline that runs on:

• Push to main or develop branches
• Pull Requests to main or develop
• Manual dispatch

Pipeline Stages:

1. Testing Matrix:

   • Python versions: 3.8, 3.9, 3.10, 3.11
   • PostgreSQL integration testing
   • Code quality checks (Black, isort, flake8)
   • Test coverage reporting

2. Security Scanning:

   • Bandit security linting
   • Safety vulnerability checking
   • Security report artifacts

3. Build & Package:

   • Python package building
   • Package validation with twine
   • Build artifact uploads

4. Docker:

   • Multi-stage Docker builds
   • Container health testing
   • Image validation

Code Quality Standards

• Code Formatting: Black (88 char line length)
• Import Sorting: isort (Black compatible)
• Linting: flake8 with complexity checks
• Test Coverage: Minimum 80% required

---

✅ License

This project is licensed under the MIT License.

---

💻 Development Workflow

Getting Started

1. Clone and Setup:

   git clone https://github.com/yourname/stacking_pr.git
   cd stacking_pr
   make setup
   

2. Install Dependencies:

   # Production dependencies
   pip install -e .
   
   # Development dependencies
   pip install -e ".[dev]"
   
   # Test dependencies  
   pip install -e ".[test]"
   
   # All dependencies
   pip install -e ".[dev,test]"
   

3. Run Tests:

   make test-cov
   

4. Start Development Server:

   # Local development
   make run
   
   # Docker development
   make docker
   make migrate
   

Development Best Practices

• Code Formatting: Run black app tests before committing
• Import Sorting: Run isort app tests before committing
• Linting: Run flake8 app to check code quality
• Testing: Maintain 80%+ test coverage
• Commits: Use conventional commit messages

Pre-commit Checklist

black app tests          # Format code
isort app tests          # Sort imports
flake8 app              # Lint code
make test-cov           # Run tests with coverage

---

🚀 Coming Soon

• 🌐 Deployment configurations (Render/Railway/Docker)
• 📊 Advanced monitoring and logging
• 🔐 Authentication and authorization
• 👁️ Optional frontend in React or HTML
• 📈 Performance optimization guides

---

Made with ❤️ by Hitesh Arora.