🐾 Cat Charity Fund — FastAPI

A production-oriented backend for managing charity projects and donations.
Create projects with target amounts, accept user donations that are automatically invested into open projects, and export reports to Google Sheets via a service account.
Built with FastAPI, SQLAlchemy (async), Alembic, Pydantic, Uvicorn, and pytest.

---

📌 About the Project

Cat Charity Fund provides a clean, pragmatic API for a small charity workflow:

• 🧱 Projects — name, description, target amount; lifecycle tracking until fully funded
• 💸 Donations — user contributions are auto-allocated into active projects (oldest-first) until targets are reached
• 🔐 Auth & roles — endpoints protected; privileged operations restricted
• 📊 Reports — a Google Sheets report with the fastest-closed projects (via service account)
• 🧪 Reliability — migrations, validations, tests, and typed schemas

---

🧰 Tech Stack

---

✨ Features

• 🏗 Create & manage projects — name, description, target amount; track funding progress
• 🔄 Automatic investment — donations are distributed into open projects until goals are met
• 👤 User management & access control — protected endpoints, role-limited mutations
• 🧾 Google Sheets reporting — generate a spreadsheet with completion-speed leaderboard
• 🛡 Strong validation & architecture — Pydantic schemas, async SQLAlchemy models, CRUD & service layers
• 🧬 Migrations — database changes via Alembic
• 🧪 Testing — pytest coverage and a Postman collection for API checks
• 📜 Interactive API docs — OpenAPI available at /docs and /redoc

---

🚀 Quick Start

Clone the repository:

git clone https://github.com/Riadnov-dev/cat_charity_fund.git
cd cat_charity_fund

Create and activate a virtual environment:

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

Upgrade pip and install dependencies:

python -m pip install --upgrade pip
pip install -r requirements.txt

Create a .env in the project root (see examples below), then run migrations:

alembic upgrade head

Start the application:

uvicorn app.main:app --reload

Open API docs in browser:

Swagger UI: http://127.0.0.1:8000/docs

Redoc: http://127.0.0.1:8000/redoc

🔐 Environment Variables

Minimal example:

DATABASE_URL=sqlite+aiosqlite:///./fastapi.db

SECRET=your_secret_key

Google service account (for report generation) — enable Google Sheets API and Google Drive API in Google Cloud, create a service account, and copy its JSON fields into .env. Also add your personal Gmail to receive access to the report:

[email protected]
TYPE=service_account
PROJECT_ID=...
PRIVATE_KEY_ID=...
PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
[email protected]
CLIENT_ID=...
AUTH_URI=https://accounts.google.com/o/oauth2/auth
TOKEN_URI=https://oauth2.googleapis.com/token
AUTH_PROVIDER_X509_CERT_URL=https://www.googleapis.com/oauth2/v1/certs
CLIENT_X509_CERT_URL=...

Tip: keep the private key quoted exactly as in JSON (with \n line breaks).

📌 API Endpoints

Projects

GET /projects/ — Get a list of all charity projects

POST /projects/ — Create a new project (superuser only)

PATCH /projects/{id} — Update a project (superuser only)

DELETE /projects/{id} — Delete a project (superuser only)

Donations

GET /donations/ — Get a list of all donations (superuser only)

POST /donations/ — Create a donation (authenticated users only)

GET /donations/my — Get donations made by the current user (authenticated users only)

Users & Auth

POST /auth/jwt/login — Authenticate a user

POST /auth/register — Register a new user

GET /users/ — List all users (superuser only)

PATCH /users/{id} — Update user information (superuser only)

(User deletion is disabled)

Reports

GET /reports/ — Generate a Google Sheets report for completed projects (superuser only)

🧪 Tests

Run the test suite:

pytest

🗄️ Database & Migrations

Run migrations (create/update DB schema):

alembic upgrade head

Create a new migration (if you change models):

alembic revision -m "your message"
alembic upgrade head

Database URL uses SQLAlchemy DSN (async driver shown in examples).

📂 Project Structure

cat_charity_fund/
├─ alembic/
│  ├─ versions/               # migration scripts
│  ├─ env.py
│  └─ script.py.mako
├─ app/
│  ├─ api/
│  │  ├─ endpoints/           # charity_project.py, donation.py, google_api.py, user.py
│  │  ├─ routers.py
│  │  └─ validators.py
│  ├─ core/                   # base, config, db (async engine/session), init_db, user
│  ├─ crud/                   # base CRUD + business entities
│  ├─ models/                 # SQLAlchemy models (project, donation, user)
│  ├─ schemas/                # Pydantic schemas
│  ├─ services/               # investment logic, Google API integration
│  └─ main.py                 # FastAPI app
├─ postman_collection/
├─ tests/
├─ openapi.json
├─ requirements.txt
├─ alembic.ini
├─ fastapi.db / test.db       # local SQLite (ignored/for dev)
├─ pytest.ini
└─ README.md

👤 Author

Nikita Riadnov

GitHub: https://github.com/Riadnov-dev