{"id":36946940,"url":"https://github.com/heisdanielade/api-smart-savings","last_synced_at":"2026-01-25T02:02:49.902Z","repository":{"id":327305471,"uuid":"1075783084","full_name":"heisdanielade/api-smart-savings","owner":"heisdanielade","description":"FastAPI backend delivering modular REST APIs  and WebSocket streams for a smart savings app with Redis caching.","archived":false,"fork":false,"pushed_at":"2026-01-22T15:14:52.000Z","size":3831,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-22T15:33:06.319Z","etag":null,"topics":["alembic","automation","background-jobs","docker","fastapi","group-savings","pydantic"],"latest_commit_sha":null,"homepage":"https://smartsave.samedov.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heisdanielade.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-14T01:39:37.000Z","updated_at":"2026-01-22T15:17:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/heisdanielade/api-smart-savings","commit_stats":null,"previous_names":["heisdanielade/api-smart-savings"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/heisdanielade/api-smart-savings","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heisdanielade%2Fapi-smart-savings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heisdanielade%2Fapi-smart-savings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heisdanielade%2Fapi-smart-savings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heisdanielade%2Fapi-smart-savings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heisdanielade","download_url":"https://codeload.github.com/heisdanielade/api-smart-savings/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heisdanielade%2Fapi-smart-savings/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28741635,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T01:40:51.112Z","status":"online","status_checked_at":"2026-01-25T02:00:06.841Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alembic","automation","background-jobs","docker","fastapi","group-savings","pydantic"],"created_at":"2026-01-13T11:32:36.253Z","updated_at":"2026-01-25T02:02:49.897Z","avatar_url":"https://github.com/heisdanielade.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💰 SmartSave - GDPR-Compliant Savings App (EU/Poland)\n\n![API Version](https://img.shields.io/badge/API%20version-v1.0.0-blue.svg)\n[![FastAPI](https://img.shields.io/badge/FastAPI-009485.svg?logo=fastapi\u0026logoColor=white)](https://fastapi.tiangolo.com/)\n[![Python](https://img.shields.io/badge/Python-3776AB?logo=python\u0026logoColor=fff)](https://www.python.org/)\n[![Pydantic](https://img.shields.io/badge/Pydantic-E92063?logo=Pydantic\u0026logoColor=white)](https://docs.pydantic.dev/)\n[![Pytest](https://img.shields.io/badge/Pytest-fff?logo=pytest\u0026logoColor=000)](https://docs.pytest.org/)\n[![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker\u0026logoColor=fff)](https://www.docker.com/)\n[![Postgres](https://img.shields.io/badge/Postgres-%23316192.svg?logo=postgresql\u0026logoColor=white)](https://www.postgresql.org/)\n[![Redis](https://img.shields.io/badge/Redis-%23DD0031.svg?logo=redis\u0026logoColor=white)](https://redis.io/)\n[![Bash](https://img.shields.io/badge/Bash-4EAA25?logo=gnubash\u0026logoColor=fff)](https://www.gnu.org/software/bash/)\n[![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-2088FF?logo=github-actions\u0026logoColor=white)](https://github.com/features/actions)\n\n## Overview\n\n**SmartSave** is a GDPR-compliant smart savings application designed for users in the EU, focusing on transparency, collaboration, and security.  \nIt combines traditional savings with AI-powered financial insights via the **SaveBuddy AI assistant**, allowing users to manage personal and group savings easily, while keeping their data private and secure.  \n\n## Contributors\n\n| Developer | GitHub Username | Responsibilities                                                                                                                                       |\n|------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Daniel Adediran | [@heisdanielade](https://github.com/heisdanielade) | **Core Backend, DevOps \u0026 Frontend** - repo management, authentication, profile \u0026 wallet management, savings, GDPR, notifications, CI/CD, SaveBuddy AI \u0026 frontend dev |\n| Danylo Samedov | [@DanSamedov](https://github.com/DanSamedov) | **Core Backend \u0026 Frontend** - authentication, profile \u0026 wallet management, transactions, savings, testing, SaveBuddy AI \u0026 frontend dev                 |\n| Artem Ruzhevych | [@ArtemRuzhevych](https://github.com/ArtemRuzhevych) | **AI \u0026 Backend integrations** - SaveBuddy AI system, logging, notifications, user analytics, GDPR, API metrics, research and testing                                   |\n\n## Table of Contents\n  \n1. [Features](#features)  \n2. [Snapshots](#snapshots)  \n3. [Architecture](#architecture)  \n4. [Authentication](#authentication)  \n5. [Authorization](#authorization)  \n6. [GDPR Compliance](#gdpr-compliance)  \n7. [Core Savings](#core-savings)  \n8. [Technologies \u0026 Design Decisions](#technologies--design-decisions)\n9. [Future Improvements](#future-improvements)  \n10. [Closing Note](#closing-note)\n\n## Features\n\n- Individual and group savings management  \n- AI savings assistant (**SaveBuddy**) for automation, requires user consent  \n- GDPR-compliant data handling and user privacy management  \n- Email-based OTP verification and secure login (JWT \u0026 OAuth)\n- Detailed requests logging with hashed IPs  \n- Rate limiting, and background email notifications  \n- CI/CD integration for automated deployments  \n- Redis caching and PostgreSQL indexing for performance  \n- Modular and scalable monorepo architecture  \n\n---\n\n## Architecture\n\n### Monorepo \u0026 Modular Design\n\nSmartSave uses a **modular architecture** within a **monorepo** setup.  \nEach feature lives in its own module under the `modules/` directory, designed for separation of concerns and ease of scaling.\n\n**Modules:**\n\n- `auth` — authentication and authorization logic  \n- `gdpr` — GDPR compliance and user data management  \n- `user` — user profile and preferences  \n- `rbac` — admin actions and access control  \n- `wallet` — wallet creation and balance management  \n- `savings` — individual and group savings  \n- `notifications` — email-based user notifications  \n- `shared` — reusable schemas and utilities\n\nEach module contains:\n\n```yaml\n  repository.py # Database access layer\n  models.py # Database models (except Auth module)\n  schemas.py # Pydantic schemas\n  service.py # Business logic\n  helpers.py # Utility functions (optional)\n```\n\n### API \u0026 Infrastructure Highlights\n\n- **Versioning:** `/v1/...` URL structure for all endpoints  \n- **Docs:** Swagger \u0026 ReDoc available at `/v1/docs` (protected with Basic Auth)  \n- **Rate Limiting:** `Per-minute/hour` restrictions per IP  \n- **Redis:** Used for `caching` and fast data retrieval with reasonable TTLs + manual cache invalidation\n- **Logging:** Structured `JSON logs` per request, with hashed IP addresses  \n- **Makefile:** Common commands for Docker, Alembic, and Pytest  \n- **Scripts:** Dev and prod startup scripts in `scripts/`  \n- **Database:** PostgreSQL + Alembic for `DB migrations`  \n- **CI/CD:** GitHub Actions workflows (`ci.yml`, `cd.yml`)  \n- **Environment:** `.env.example` provided for configuration variables  \n\n**Backend System Flow:**  \n\n```bash\n  Middleware → Router → Service → Repository → Database\n```\n\n---\n\n## Authentication\n\nSmartSave uses a secure, stateless authentication system built with **JWT (JSON Web Tokens)** and **Email-based OTP (One-Time Password)** verification.\n\n- **Registration**: Secure onboarding with 6-digit OTP verification.\n- **Security**: Account locking after failed attempts and real-time login notifications.\n- **Global Logout**: Immediate token invalidation via versioning.\n\n👉 **[Read the full Authentication breakdown here](docs/features/AUTHENTICATION.md)**\n\n---\n\n## Authorization\n\nPermissions are managed through a fine-grained **Role-Based Access Control (RBAC)** system, ensuring data integrity and user privacy.\n\n- **Roles**: Distinct permissions for `USER`, `ADMIN`, and `SUPER_ADMIN`.\n- **Integrity**: Financial data (wallets and transactions) is immutable and append-only.\n- **RBAC**: Guarded endpoints using FastAPI dependency injection.\n\n👉 **[Read the full Authorization breakdown here](docs/features/AUTHORIZATION.md)**\n\n---\n\n## GDPR Compliance\n\nPrivacy is a first-class citizen in SmartSave. The application is built around the core principles of the **General Data Protection Regulation (GDPR)**.\n\n- **Data Rights**: Full support for Right to Access (Encrypted PDF exports) and Right to Forget (Anonymization).\n- **Log Privacy**: Irreversible hashing of IP addresses in all system logs.\n- **Consent**: AI-powered features like **SaveBuddy** require explicit user consent.\n\n👉 **[Read the full GDPR Compliance breakdown here](docs/features/GDPR.md)**\n\n---\n\n## Caching with Redis\n\nTo improve performance and reduce database load, we implemented **Redis caching** for frequently accessed endpoints, optimizing both latency and scalability.\n\n👉 **[Read the full Caching breakdown here](docs/features/CACHING.md)**\n\n---\n\n## Core Savings\n\nSmartSave provides a comprehensive system for individual and collaborative savings, backed by a secure virtual wallet.\n\n- **Individual Goals**: Set personal targets and track progress.\n- **Group Squads**: Save together with shared goals and real-time history.\n- **Wallet Hub**: Centralized balance management with multi-currency support.\n\n👉 **[Read the full Savings \u0026 Wallet breakdown here](docs/features/SAVINGS.md)**\n\n---\n\n## Technologies \u0026 Design Decisions\n\n| Technology | Purpose | Design Relation |\n|-------------|----------|-----------------|\n| **FastAPI** | High-performance backend \u0026 auto-generated docs | Enables clear dependency injection and modular design |\n| **Pydantic** | Data validation and serialization | Supports DRY and type-safe schema sharing |\n| **SQLModel + SQLAlchemy** | ORMs for PostgreSQL | Enforces consistent data access layer (Repository pattern) |\n| **Alembic** | Database migrations | Streamlined schema versioning |\n| **Slow-api** | Rate-limiting | For security and simplified implementation |\n| **Redis** | Caching | Optimizes performance and scalability |\n| **Docker** | Containerization | Simplifies setup and deployment |\n| **Pytest** | Automated testing | Ensures reliability and regression safety |\n| **GitHub Actions** | CI/CD pipeline | Automates testing and deployment |\n| **React** | Frontend | User interface and experience |\n| **Tailwind CSS** | Styling | Responsive and modern design |\n| **Vite** | Build tool | Fast and modern frontend development |\n\n### Design Principles/Patterns in Action\n\n- **SOLID:** Dependency Injection in routers promotes modular and testable code.  \n- **DRY:** Shared helpers and reusable service methods minimize duplication.  \n- **Separation of Concerns:** Clear flow: *Middleware → Router → Service → Repository*.  \n- **Extensibility:** Notification service follows the **ABC pattern**, allowing easy integration of SMS or push services in the future.\n- **Factory + Registry Pattern:** The email notification system uses a combination of design patterns:\n  - **Factory Pattern** (`EmailProviderFactory`): Dynamically selects the email provider (SMTP or Resend) based on configuration, enabling easy switching between providers without code changes.\n  - **Registry Pattern** (`EMAIL_TEMPLATES`): Maps notification types to their corresponding templates, subjects, and context models in a centralized dictionary, making it simple to add new notification types.\n  - **Strategy Pattern** (`EmailProvider` ABC): Defines a common interface for different email providers, allowing interchangeable implementations while maintaining consistent behavior.\n  - This architecture ensures the notification system is flexible, maintainable, and easily extensible for new providers or notification types.\n\n---\n\n## Snapshots\n\nFew snapshots of the frontend screens, backend endpoints, email templates \u0026 API responses.\n\n### Frontend View (Desktop)\n\n| Description       | Preview                                                                |\n|-------------------|------------------------------------------------------------------------|\n| **Landing Page**  | ![Landing Page](assets/images/frontend/landing.png)                    |\n| **Login Page**    | ![Login Page](./assets/images/frontend/login.png)                      |\n| **User Dashboard** | ![User Dashboard](assets/images/frontend/user_dashboard.png)           |\n| **User Profile**  | ![User Profile](assets/images/frontend/user_profile.png)               |\n| **Transactions**  | ![Transactions](assets/images/frontend/transactions.png)               |\n| **Group Details** | ![Group Details](assets/images/frontend/group_details.png)             |\n| **Group Members** | ![Group Members](assets/images/frontend/group_members.png)             |\n| **Group Chat**    | ![Group Chat](assets/images/frontend/group_chat.png)                   |\n| **Withdraw from Group** | ![Withdraw from Group](assets/images/frontend/withdraw_from_group.png) |\n| **Data Report Request** | ![Data Report Request](./assets/images/frontend/gdpr_data_request.png) |\n\n### Frontend View (Mobile)\n\n| Description       | Preview                                                                |\n|-------------------|------------------------------------------------------------------------|\n| **Mobile Dashboard** | ![Mobile Dashboard](assets/images/frontend/mobile_user_dashboard.png) |\n| **Mobile Groups**    | ![Mobile Groups](assets/images/frontend/mobile_groups.png)            |\n| **Mobile Chat**      | ![Mobile Chat](assets/images/frontend/mobile_group_chat.png)          |\n| **Mobile Transactions** | ![Mobile Transactions](assets/images/frontend/mobile_transactions.png) |\n\n### API Endpoints (Swagger)\n\n| Description               | Preview                                                                              |\n|---------------------------|--------------------------------------------------------------------------------------|\n| **Authentication**        | ![Authentication Endpoints](./assets/images/endpoints/auth.png)                      |\n| **Account \u0026 GDPR**        | ![Account Management \u0026 GDPR Endpoints](./assets/images/endpoints/account_gdpr.png) |\n| **Wallet \u0026 Transactions** | ![Wallet \u0026 Transactions Endpoints](./assets/images/endpoints/wallet.png)             |\n| **Admin \u0026 Groups**        | ![Admin \u0026 Groups Endpoints](./assets/images/endpoints/admin_groups.png)            |\n\n### Email Templates\n\n| Description           | Preview                                                              |\n|-----------------------|----------------------------------------------------------------------|\n| **Login Notification** | ![Login Notification](./assets/images/emails/login_notification.png) |\n| **Reset Password**    | ![Reset Password](./assets/images/emails/reset_password.png)         |\n| **GDPR Data Export**  | ![GDPR Data Export](./assets/images/emails/gdpr_data_export.png)     |\n| **Wallet Deposit**    | ![Wallet Deposit](./assets/images/emails/wallet_deposit.png)         |\n\n### API Responses\n\n| Description             | Preview                                                                   |\n|-------------------------|---------------------------------------------------------------------------|\n| **Wallet Deposit**      | ![Wallet Deposit](./assets/images/responses/wallet_deposit.png)           |\n| **Wallet Transactions** | ![Wallet Transactions](./assets/images/responses/wallet_transactions.png) |\n\n---\n\n## Future Improvements\n\n- Introduce **referral system** for user growth.  \n- Split modules into **dedicated microservices** for better scalability.  \n- Integrate **real banking APIs** for live savings and transactions.  \n- Add **SMSNotificationService** and **push notifications**.  \n- Expand **SaveBuddy AI** to provide personalized financial recommendations.\n\n---\n\n## Closing Note\n\nSmartSave was initially designed as a final-year project by 3 students from the `University of Zielona Gora - Computer Science \u0026 Econometrics` but advanced to a production-grade system. It's not just a financial tool but a **trustworthy digital companion** for responsible saving.  \nBuilt with transparency, collaboration, and user privacy at its core; this project is a foundation for modern, ethical financial technology.\n\n**Thank you for checking out SmartSave! 💚**\n\n## License\n\nThis project is licensed under a **STRICT PROPRIETARY LICENSE**.\n**Strictly prohibited:**\n\n- Automated scraping or data mining.\n- AI training, fine-tuning, or evaluation using this codebase.\n- Redistribution without explicit written permission.\n\nSee the [LICENSE](LICENSE) file for full details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheisdanielade%2Fapi-smart-savings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheisdanielade%2Fapi-smart-savings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheisdanielade%2Fapi-smart-savings/lists"}