💰 SmartSave - GDPR-Compliant Savings App (EU/Poland)

Overview

SmartSave is a GDPR-compliant smart savings application designed for users in the EU, focusing on transparency, collaboration, and security.
It 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.

Contributors

Developer	GitHub Username	Responsibilities
Daniel Adediran	@heisdanielade	Core Backend, DevOps & Frontend - repo management, authentication, profile & wallet management, savings, GDPR, notifications, CI/CD, SaveBuddy AI & frontend dev
Danylo Samedov	@DanSamedov	Core Backend & Frontend - authentication, profile & wallet management, transactions, savings, testing, SaveBuddy AI & frontend dev
Artem Ruzhevych	@ArtemRuzhevych	AI & Backend integrations - SaveBuddy AI system, logging, notifications, user analytics, GDPR, API metrics, research and testing

Table of Contents

1. Features
2. Snapshots
3. Architecture
4. Authentication & Authorization
5. GDPR Compliance
6. Core Savings
7. Technologies & Design Decisions
8. Future Improvements
9. Closing Note

---

Features

• Individual and group savings management
• AI savings assistant (SaveBuddy) for automation, requires user consent
• GDPR-compliant data handling and user privacy management
• Email-based OTP verification and secure login (JWT & OAuth)
• Detailed requests logging with hashed IPs
• Rate limiting, and background email notifications
• CI/CD integration for automated deployments
• Redis caching and PostgreSQL indexing for performance
• Modular and scalable monorepo architecture

---

Architecture

Monorepo & Modular Design

SmartSave uses a modular architecture within a monorepo setup.
Each feature lives in its own module under the modules/ directory, designed for separation of concerns and ease of scaling.

Modules:

• auth — authentication and authorization logic
• gdpr — GDPR compliance and user data management
• user — user profile and preferences
• wallet — wallet creation and balance management
• savings — individual and group savings
• notifications — email-based user notifications
• shared — reusable schemas and utilities

Each module contains:

  repository.py # Database access layer
  models.py # Database models (except Auth module)
  schemas.py # Pydantic schemas
  service.py # Business logic
  helpers.py # Utility functions (optional)

API & Infrastructure Highlights

• Versioning: /v1/... URL structure for all endpoints
• Docs: Swagger & ReDoc available at /v1/docs (protected with Basic Auth)
• Rate Limiting: Per-minute/hour restrictions per IP
• Redis: Used for caching and fast data retrieval with reasonable TTLs + manual cache invalidation
• Logging: Structured JSON logs per request, with hashed IP addresses
• Makefile: Common commands for Docker, Alembic, and Pytest
• Scripts: Dev and prod startup scripts in scripts/
• Database: PostgreSQL + Alembic for DB migrations
• CI/CD: GitHub Actions workflows (ci.yml, cd.yml)
• Environment: .env.example provided for configuration variables

Backend System Flow:

  Middleware → Router → Service → Repository → Database

---

Authentication & Authorization

1. User registers with email and password.
2. A 6-digit OTP is sent to the user’s email for verification.
3. Once verified, user.is_verified is set to True.
4. On successful login, a JWT is issued and used for all authenticated requests.
5. Failed logins increment user.failed_login_attempts; exceeding the limit locks the account.
6. Locked accounts trigger a notification email to the user.
7. Roles are defined as:
   • USER: Full access to own data only
   • ADMIN: Limited create/read access except GDPR/user/wallet data
   • SUPER_ADMIN: Full CRUD access (excluding wallet/transactions modification)

Wallets and transactions are immutable - they cannot be modified or deleted once created.

---

GDPR Compliance

SmartSave was built around the three core GDPR principles:

1. Right to Access Data
2. Right to Modify Data
3. Right to Delete Data

Key Implementations

• IP addresses are stored as irreversible hashes in logs.
• Users can request a data report, delivered as a password-protected PDF via email.
• Data modification is allowed through the app or via support requests.
• Account deletions are soft-deleted for 365 days before anonymization (duration is easily configurable).
• Anonymization Process:
  • All PII replaced with random values.
  • User can no longer log in.
  • Maintains referential integrity for financial auditing.
• Logs older than 30 days are auto-deleted.
• GDPR requests are logged in a dedicated GDPRRequest table.
• After two years, even the anonymized GDPR requests are removed.

---

Caching with Redis

To improve performance and reduce database load, we implemented Redis caching for frequently accessed endpoints, i.e:

• GET /user/me
• GET /wallet/transactions

How It Works

1. Cache Key Naming:
   Keys follow a consistent pattern to avoid collisions and allow easy invalidation:

   • Current user: user_current:{user_email}
   • Wallet transactions: wallet_transactions:{user_id}:page:{page}:size:{page_size}

2. Cache Retrieval:
   Before hitting the database, the application checks Redis for the cached data.

   • If a cache hit occurs, the JSON data is returned immediately.
   • If a cache miss occurs, the data is fetched from the database, cached in Redis, and then returned.

3. Time-to-Live (TTL):
   Cached data expires after a default TTL (10 minutes) / custom TTL set for each cache store, to ensure freshness.

4. Cache Invalidation:
   Whenever the underlying data changes (e.g., user updates, new transactions), the relevant cache keys are invalidated automatically to prevent stale data.

5. Performance Impact:

   • Cache miss: ~124–150ms (includes DB query)
   • Cache hit: ~50-80ms (Redis retrieval + deserialization)

This strategy ensures low-latency responses for frequently accessed endpoints while keeping the database load minimal.

---

Core Savings

Individual Savings

• Each goal (e.g., “Buy a bicycle”) is a single independent saving entry.
• Funds are allocated from the user’s wallet.
• user.locked_amount tracks funds currently in use for savings/goals.

Group Savings

• Groups have 2–7 members and one or two admins.
• Each group focuses on one shared goal.
• Contributions and withdrawals appear as chat-like transactions.
• Admins can enable approval for fund withdrawals.
• Users violating group rules (e.g., unauthorized withdrawals) are banned from rejoining for 7 days.
• Group balances are derived from members’ wallets — groups have no separate wallets.
• Groups trigger automatic notifications for:
  • Added/removed members
  • Contributions
  • Target reached (50% or 100%)

Wallet System

• Each verified user automatically gets one wallet.
• Wallet fields:
  • total_balance
  • locked_amount
  • Computed available_balance = total_balance - locked_amount
• Base app currency is EUR, but users can select from 4 additional currencies for frontend display.
• Exchange rates are fetched from an external API and cached in the DB.

---

Technologies & Design Decisions

Technology	Purpose	Design Relation
FastAPI	High-performance backend & auto-generated docs	Enables clear dependency injection and modular design
Pydantic	Data validation and serialization	Supports DRY and type-safe schema sharing
SQLModel + SQLAlchemy	ORMs for PostgreSQL	Enforces consistent data access layer (Repository pattern)
Alembic	Database migrations	Streamlined schema versioning
Slow-api	Rate-limiting	For security and simplified implementation
Redis	Caching	Optimizes performance and scalability
Docker	Containerization	Simplifies setup and deployment
Pytest	Automated testing	Ensures reliability and regression safety
GitHub Actions	CI/CD pipeline	Automates testing and deployment
React	Frontend	User interface and experience
Tailwind CSS	Styling	Responsive and modern design
Vite	Build tool	Fast and modern frontend development

Design Principles/Patterns in Action

• SOLID: Dependency Injection in routers promotes modular and testable code.
• DRY: Shared helpers and reusable service methods minimize duplication.
• Separation of Concerns: Clear flow: Middleware → Router → Service → Repository.
• Extensibility: Notification service follows the ABC pattern, allowing easy integration of SMS or push services in the future.
• Factory + Registry Pattern: The email notification system uses a combination of design patterns:
  • Factory Pattern (EmailProviderFactory): Dynamically selects the email provider (SMTP or Resend) based on configuration, enabling easy switching between providers without code changes.
  • 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.
  • Strategy Pattern (EmailProvider ABC): Defines a common interface for different email providers, allowing interchangeable implementations while maintaining consistent behavior.
  • This architecture ensures the notification system is flexible, maintainable, and easily extensible for new providers or notification types.

---

Snapshots

Few snapshots of the frontend screens, backend endpoints, email templates & API responses.

Frontend View (Desktop)

Description	Preview
Landing Page
Login Page
User Dashboard
User Profile
Transactions
Group Details
Group Members
Group Chat
Withdraw from Group
Data Report Request

Frontend View (Mobile)

Description	Preview
Mobile Dashboard
Mobile Groups
Mobile Chat
Mobile Transactions

API Endpoints (Swagger)

Description	Preview
Authentication
Account & GDPR
Wallet & Transactions
Admin & Groups

Email Templates

Description	Preview
Login Notification
Reset Password
GDPR Data Export
Wallet Deposit

API Responses

Description	Preview
Wallet Deposit
Wallet Transactions

---

Future Improvements

• Introduce referral system for user growth.
• Split modules into dedicated microservices for better scalability.
• Integrate real banking APIs for live savings and transactions.
• Add SMSNotificationService and push notifications.
• Expand SaveBuddy AI to provide personalized financial recommendations.

---