Forem: Kiishi_joseph

Building CashCove: A Deep Dive into Wallet Transfers, Notifications & Financial Logic

Kiishi_joseph — Thu, 24 Jul 2025 20:57:51 +0000

🧠 CashCove Series – Part 2

Building Wallet Transfers, Locked Funds & Notifications – My Thought Process

In the first part of this series, I covered authentication and the basic wallet setup for CashCove, my experimental GraphQL wallet backend. In this second part, I'll walk through how I approached wallet funding, bank transfers, locked funds, notifications, and money requests.

This isn't just about implementation — I'll also explain why I made certain decisions, what tradeoffs I considered, and how I've structured the project to be easy to maintain or scale later.

🏦 Wallet Funding

Users can fund their wallet via Paystack or any other gateway in production. But for now, I've implemented a mock resolver that mimics a successful funding flow:

await walletRepo.credit(user.id, amount);
await transactionRepo.record({
  userId: user.id,
  type: 'funding',
  amount,
  status: 'success',
});
await notificationRepo.create({
  userId: user.id,
  message: `Your wallet has been funded with ₦${amount}`,
});

💡 Why Separate Wallet and Transaction Logic?

I wanted to keep wallet mutations atomic, while transactions serve more like receipts. This separation helps in:

Supporting reconciliation later (e.g., match wallet balance against transactions).
Avoiding side effects that might accidentally double-credit or debit wallets.

📬 Real-Time Notifications

Each funding triggers a database-persisted notification, which can later be sent via email or push. For now, I've kept notifications sync and direct, but the repository is abstract enough to support queue-based delivery later.

🔄 Wallet Transfers

Transfers between users are central to a wallet system. Here's how I structured them:

✅ Flow

Ensure sender has enough available balance.
Debit sender, credit receiver.
Create transfer transaction.
Notify both parties.

const senderWallet = await walletRepo.find(user.id);
const receiverWallet = await walletRepo.findByOwner(receiverId);

await walletRepo.debit(user.id, amount);
await walletRepo.credit(receiverId, amount);

await transactionRepo.record({ type: 'transfer', from, to, amount });

The transaction resolver handles both credits and debits with proper nullable handling:

@Mutation(() => Transaction)
async createTransaction(
  @Arg("amount") amount: number,
  @Arg("type") type: "credit" | "debit",
  @Arg("currency") currency: string,
  @Arg("fromUserId", { nullable: true }) fromUserId?: string,
  @Arg("toUserId", { nullable: true }) toUserId?: string
): Promise<Transaction> {
  // Proper null handling for GraphQL
  const fromUserIdTransformed = fromUserId === null ? undefined : fromUserId;
  const toUserIdTransformed = toUserId === null ? undefined : toUserId;

  return await transactionService.createTransaction(
    amount,
    type,
    currency,
    fromUserIdTransformed,
    toUserIdTransformed
  );
}

🧠 Design Considerations

No pending state — transfers are instant and final.
Strong use of DB transactions to make sure debit + credit happen together.
Proper handling of GraphQL's null vs undefined semantics.

🔒 Locked Funds

This was an interesting challenge. I knew some funds might need to be reserved but not yet spent. For example, if someone initiates a transaction that needs verification or delivery.

💾 Schema

@Column({ type: 'int', default: 0 })
balance: number;

@Column({ type: 'int', default: 0 })
lockedBalance: number;

This allows two balances:

available = balance - lockedBalance
total = balance

🔁 Usage

When a transfer or escrow is initiated: walletRepo.incrementLock(userId, amount);
When it fails or expires: walletRepo.decrementLock(userId, amount);
When it succeeds: walletRepo.finalizeTransaction(userId, amount);

Here's how the locked funds resolver handles different scenarios:

@Mutation(() => LockedFunds)
async lockFunds(
  @Arg("walletId") walletId: string,
  @Arg("amount") amount: number,
  @Arg("currency") currency: string,
  @Arg("unlockDate") unlockDate: Date,
  @Ctx() ctx: GraphQLContext
): Promise<LockedFunds> {
  const userId = ctx.user?.userId;
  return await lockedFundService.lockFunds(
    userId,
    walletId,
    amount,
    currency,
    unlockDate
  );
}

@Mutation(() => String)
async earlyWithdrawal(
  @Arg("userId") userId: string,
  @Arg("lockedFundId") lockedFundId: string
): Promise<string> {
  const result = await lockedFundService.earlyWithdrawal(userId, lockedFundId);
  return `Withdrawal successful. Amount after penalty: ${result.amountAfterPenalty}, Penalty fee: ${result.penaltyFee}`;
}

🔐 Why Lock Instead of Deduct?

I didn't want to prematurely deduct money — especially if the final status is unknown. Locking gives you a reversible way to reserve funds. This aligns with systems like Paystack, Stripe, and marketplaces.

📉 Early Withdrawals

I've even included a requestEarlyWithdrawal() method that can allow the user to get their locked funds back — possibly with a penalty.

📬 Notifications

Every major action in the system triggers a notification:

Wallet funded
Transfer sent/received
Money request accepted/declined

They're stored in a notifications table and linked to the user. Here's what a resolver might look like:

await notificationRepo.create({
  userId: receiverId,
  message: `${senderName} sent you ₦${amount}`,
});

While they're currently just saved to DB, I structured the repo so they can later be routed through email, push, or in-app systems.

🙋 Money Requests (and Cron Expiry)

Users can send money requests to other users. I added a MoneyRequest entity with:

status (pending, accepted, denied, expired)
expiresAt

The resolver handles the full lifecycle:

@Mutation(() => MoneyRequest)
async requestMoney(
  @Arg("amount") amount: number,
  @Arg("currency") currency: string,
  @Arg("fromUserId") fromUserId: string,
  @Arg("toUserId") toUserId: string
): Promise<MoneyRequest> {
  return await moneyRequestService.createMoneyRequest(
    amount,
    currency,
    fromUserId,
    toUserId
  );
}

@Mutation(() => MoneyRequest)
async respondToMoneyRequest(
  @Arg("id") id: string,
  @Arg("status") status: string
): Promise<MoneyRequest> {
  return await moneyRequestService.respondToMoneyRequest(id, status);
}

A background cron job runs every hour to auto-expire any request past 24 hours.

if (Date.now() > request.expiresAt) {
  request.status = 'expired';
  await moneyRequestRepo.save(request);
}

This mirrors how apps like Cash App or Venmo work — you can't just leave requests hanging forever.

🔄 Bank Transfers

For withdrawing funds to external bank accounts, I've built a complete flow with proper status tracking:

export class BankTransferRepository {
  async createBankTransfer(
    userId: string,
    amount: number,
    currency: string,
    recipientBankCode: string,
    recipientAccountNumber: string,
    reference: string
  ) {
    return await prisma.bankTransfer.create({
      data: {
        user_id: userId,
        amount,
        currency,
        recipient_bank_code: recipientBankCode,
        recipient_account_number: recipientAccountNumber,
        reference,
      },
    });
  }

  async updateBankTransferStatus(reference: string, status: string) {
    return await prisma.bankTransfer.update({
      where: { reference },
      data: { status },
    });
  }
}

The resolver pattern keeps things clean:

@Mutation(() => BankTransfer)
async initiateBankTransafer(
  @CurrentUser() userId: string,
  @Arg("amount") amount: number,
  @Arg("currency") currency: string,
  @Arg("recipientBankCode") recipientBankCode: string,
  @Arg("recipientAccountNumber") recipientAccountNumber: string
): Promise<BankTransfer> {
  return await bankTransferService.initiateTransfer(
    userId,
    amount,
    currency,
    recipientBankCode,
    recipientAccountNumber
  );
}

🎯 Why Separate Initiate and Verify?

Bank transfers aren't instant like wallet-to-wallet transfers. They need:

Initial validation and submission to the bank
Webhook handling for status updates
Proper failure handling and user notifications

📱 Enhanced Notifications System

I've expanded the notification system beyond simple database storage:

export class NotificationRepository {
  async createNotification(userId: string, message: string) {
    return await prisma.notification.create({
      data: {
        user_id: userId,
        message,
      },
    });
  }

  async markNotificationAsRead(id: string) {
    return await prisma.notification.update({
      where: { id },
      data: { is_read: true },
    });
  }
}

The resolver handles both reading and marking notifications:

@Query(() => [Notification])
async getNotifications(
  @CurrentUser() userId: string
): Promise<Notification[]> {
  return await notificationService.getNotifications(userId);
}

@Mutation(() => Notification)
async markNotificationAsRead(@Arg("id") id: string): Promise<Notification> {
  return await notificationService.markNotificationAsRead(id);
}

⏰ Automated Money Request Expiry

Rather than letting money requests sit forever, I implemented a cron job that auto-expires them after 24 hours:

cron.schedule("0 * * * *", async () => {
  const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);

  const expiredRequests = await prisma.moneyRequest.findMany({
    where: {
      status: "PENDING",
      created_at: { lt: oneDayAgo },
    },
  });

  for (const request of expiredRequests) {
    await prisma.moneyRequest.update({
      where: { id: request.id },
      data: { status: "DENIED" },
    });

    await prisma.notification.create({
      data: {
        user_id: request.from_user_id,
        message: `Your money request has been automatically denied due to no response.`,
      },
    });
  }
});

This runs every hour and automatically cleans up stale requests while notifying users.

🧾 Custom Logging with Zod Validation

I built a type-safe logger that validates every log entry:

const logInputSchema = z.object({
  message: z.string(),
  params: z.union([z.array(z.any()), z.object({}).passthrough(), z.string(), z.number()]).optional(),
});

type Serverity = "WARNING" | "INFO" | "DEBUG" | "ERROR";

const logMessage = (input: LogInputType, serverity: Serverity) => {
  const validation = logInputSchema.safeParse(input);

  if(!validation.success){
    throw new Error(`Incorrect log schema: ${validation.error.message}`);
  }

  const {message, params} = validation.data;

  switch (serverity){
    case "DEBUG":
      console.debug(message, params);
      break;
    case "ERROR":
      console.error(message, params);
      break;
    // ... other cases
  }
};

🤔 Why Build a Custom Logger?

While I plan to switch to Pino or Winston for production, this custom solution gives me:

Type safety with Zod validation
Consistent log structure across the app
Easy migration path when I'm ready to upgrade

🛡️ Authentication Pattern

I've used a consistent authentication pattern across all resolvers with a custom @CurrentUser() decorator:

export function CurrentUser() {
  return createParameterDecorator<GraphQLContext>(({ context }) => {
    if (!context.user?.userId)
      throw new AppError("Unauthorized: User ID is missing", 401);

    return context.user?.userId;
  });
}

This eliminates repetitive auth checks and ensures consistent error handling:

@Query(() => [Wallet])
async getWallets(@CurrentUser() userId: string): Promise<Wallet[]>{
  return await walletService.getWallets(userId);
}

🎯 Wrapping Up

This completes the core functionality for CashCove! I've built a solid foundation with:

✅ Wallet funding and transfers
✅ Locked funds with early withdrawal penalties
✅ Real-time notifications with read/unread states
✅ Money requests with automatic expiry
✅ Bank transfer initiation and verification
✅ Type-safe logging and consistent authentication

🚀 Future Enhancements

While the system is fully functional, there are some features I might add down the road:

Paystack integration for real payment processing (currently using mock funding)
Enhanced activity history with filtering and pagination
Webhook handling for bank transfer status updates
Email/SMS notifications beyond database storage
Rate limiting and advanced security features

The codebase is structured to make these additions straightforward when needed.

🔗 Explore the Code

Want to dive deeper? Check out the full implementation on GitHub: CashCove

Thanks for following along! If you found this helpful or have questions about any of the implementation details, drop a comment below. 💬

Building A Wallet System - Part 1: Authentication with Apollo Server

Kiishi_joseph — Fri, 27 Jun 2025 19:49:21 +0000

Hey folks! 👋

This is Part 1 of a blog series where I document how I’m building CashCove — a simplified wallet backend. I’m using GraphQL, Apollo Server, Prisma, and a clean repository-service architecture.

👉 GitHub Repo: https://github.com/adeoluwa/CashCove

📘 Note: This guide assumes you're already comfortable setting up a Node.js project with TypeScript and Prisma. If not, check out the Prisma Getting Started Guide first.

Also, I noticed the back cover image looks cool 😄

🎯 Why GraphQL? (Even as a First-Time User)

This is my first proper project using GraphQL, and I picked it because:

I wanted to try something new beyond REST.
I love how GraphQL gives the client control over the data it wants.
Apollo Server + TypeGraphQL makes schema management really smooth.

So this blog is also a learning journal.

🧱 Tech Stack Overview

Apollo Server for the GraphQL API
Prisma ORM with SQLite
TypeGraphQL for decorator-based schema generation
Repository-Service Pattern for scalable logic and clean separation of concerns

🗂️ Project Structure

CashCove/
├── src/
│   ├── resolvers/       # GraphQL resolvers (auto-loaded)
│   ├── services/        # Business logic lives here
│   ├── repositories/    # All Prisma DB operations
│   ├── utils/           # Auth utils, helpers
│   ├── middleware/      # Auth & error handling
│   ├── loaders/         # Resolver loader
│   ├── types/           # Custom context types, etc.
│   ├── index.ts         # App entry point
│   └── prisma.ts        # Singleton Prisma client
└── schema.prisma        # Prisma schema

🧬 Prisma User Model

For this part, we only focus on the User model (simplified for authentication):

model User {
  id             String   @id @default(uuid())
  email          String   @unique
  password       String
  account_number String
  address        String?
  phone_number   String?
  created_at     DateTime @default(now())
  updated_at     DateTime @updatedAt
  state          UserState @default(ACTIVE)

  @@map("users")
}

enum UserState {
  ACTIVE
  SUSPENDED
}

We're using SQLite for local development, but Prisma makes it easy to switch providers later.

🛠️ Prisma Singleton

To prevent multiple Prisma connections, we use a singleton class:

// src/prisma.ts
import { PrismaClient } from "@prisma/client";

export class PrismaSingleton {
  private static instance: PrismaClient;

  public static getInstance(): PrismaClient {
    if (!PrismaSingleton.instance) {
      PrismaSingleton.instance = new PrismaClient();
    }
    return PrismaSingleton.instance;
  }
}

const prisma = PrismaSingleton.getInstance();
export default prisma;

🧠 Auth Utilities

We hash passwords and generate tokens:

import bcrypt from "bcryptjs";
import jwt from "jsonwebtoken";

dotenv.config();

export async function hashPassword(password: string) {
  return await bcrypt.hash(password, 10);
}

export async function verifyPassword(password: string, hashed: string) {
  return await bcrypt.compare(password, hashed);
}

export function generateToken(userId: string) {
  return jwt.sign({ userId }, process.env.JWT_SECRET!, { expiresIn: "1h" });
}

🧾 User Repository

// src/repositories/user.repository.ts
import prisma from "../prisma";

export class UserRepository {
  async findUserByEmail(email: string) {
    return prisma.user.findUnique({ where: { email } });
  }

  async findUserById(id: string) {
    return prisma.user.findUnique({ where: { id } });
  }

  async createUser(email: string, password: string, accountNumber: string) {
    return prisma.user.create({
      data: {
        email,
        password,
        account_number: accountNumber,
      },
    });
  }

  async updateUserProfile(id: string, updates: any) {
    return prisma.user.update({ where: { id }, data: updates });
  }
}

🧩 User Service

This class handles logic like validation, hashing, and normalizing data:

import { UserRepository } from "../repositories/user.repository";
import { hashPassword, verifyPassword } from "../utils/auth";
import isEmail from "validator/lib/isEmail";

export class UserService {
  constructor(private userRepository = new UserRepository()) {}

  private generateAccountNumber() {
    return Math.floor(1000000000 + Math.random() * 9000000000).toString();
  }

  private normalizeEmail(email: string) {
    return email.trim().toLowerCase();
  }

  async register(email: string, password: string) {
    const normalizedEmail = this.normalizeEmail(email);
    if (!isEmail(normalizedEmail)) throw new Error("Invalid email format");

    const existing = await this.userRepository.findUserByEmail(normalizedEmail);
    if (existing) throw new Error("Account already in use!");

    const hashedPassword = await hashPassword(password);
    return this.userRepository.createUser(
      normalizedEmail,
      hashedPassword,
      this.generateAccountNumber()
    );
  }

  async login(email: string, password: string) {
    const normalizedEmail = this.normalizeEmail(email);
    const user = await this.userRepository.findUserByEmail(normalizedEmail);
    if (!user) throw new Error("User not found");
    if (!(await verifyPassword(password, user.password)))
      throw new Error("Invalid credentials");

    return user;
  }

  async updateUsersProfile(
    id: string,
    updates: Partial<{ address: string; phone_number: string }>
  ) {
    if ("email" in updates || "account_number" in updates)
      throw new Error("Email and account number cannot be updated");

    const user = await this.userRepository.findUserById(id);
    if (!user) throw new Error("User not found");

    return this.userRepository.updateUserProfile(id, updates);
  }
}

🧠 User Schema

The schema defines how data enters and exits the application.

import { Field, InputType, ObjectType } from "type-graphql";

@ObjectType()
export class User {
  @Field() id!: string;
  @Field() email!: string;
  @Field() account_number!: string;
  @Field(() => String, { nullable: true }) address?: string | null;
  @Field(() => String, { nullable: true }) phone_number?: string | null;
  @Field(() => Date, { nullable: true }) created_at?: Date;
}

@InputType()
export class RegisterInput {
  @Field() email!: string;
  @Field() password!: string;
}

@InputType()
export class LoginInput {
  @Field() email!: string;
  @Field() password!: string;
}

@InputType()
export class UpdateProfileInput {
  @Field({ nullable: true }) address?: string;
  @Field({ nullable: true }) phone_number?: string;
}

@ObjectType()
export class LoginResponse {
  @Field() token!: string;
  @Field(() => User, { nullable: true }) user!: User | null;
}

🧑‍💻 User Resolver

In GraphQL APIs, resolvers serve the same fundamental purpose as controllers do in REST APIs - they act as the primary entry points that handle incoming requests, orchestrate business logic, and return responses.

import { Arg, Mutation, Query, Resolver } from "type-graphql";
import { UserService } from "../services/user.service";
import {
  RegisterInput,
  LoginInput,
  User,
  UpdateProfileInput,
  LoginResponse,
} from "../schemas/user.schema";
import { generateToken } from "../utils/auth";
import { CurrentUser } from "../middleware/currentUser";

const userService = new UserService();

@Resolver()
export default class UserResolver {
  @Query(() => String)
  hello() {
    return "Hello, there!";
  }

  @Mutation(() => User)
  async register(@Arg("input") input: RegisterInput): Promise<User> {
    return await userService.register(input.email, input.password);
  }

  @Mutation(() => LoginResponse)
  async login(@Arg("input") input: LoginInput): Promise<LoginResponse> {
    const user = await userService.login(input.email, input.password);
    const token = generateToken(user.id);

    return {
      token,
      user: {
        id: user.id,
        email: user.email,
        account_number: user.account_number,
        phone_number: user.phone_number,
        address: user.address,
      },
    };
  }

  @Mutation(() => User)
  async updateProfile(
    @CurrentUser() userId: string,
    @Arg("input") input: UpdateProfileInput
  ): Promise<User> {
    return await userService.updateUsersProfile(userId, input);
  }
}

📦 Auto-Loading Resolvers

In a GraphQL server setup using TypeGraphQL, all resolvers must be registered in the schema during initialization. Instead of manually importing and registering each resolver in index.ts, we automate this process using a loadResolvers.ts utility. This greatly reduces boilerplate and ensures scalability as the number of resolvers grows.

Here's how it works

// src/loaders/loadResolvers.ts
import path from "path";
import fs from "fs";
//import { Resolver, Query } from "type-graphql";

export default async function loadResolvers(): Promise<Function[]> {
  const dir = path.join(__dirname, "../resolvers");
  const files = fs.readdirSync(dir).filter((f) => f.endsWith("resolver.ts"));

  const resolvers = await Promise.all(
    files.map(async (file) => {
      const mod = await import(path.join(dir, file));
      return mod.default;
    })
  );

  return resolvers.length? resolvers : [DefaultResolver];
}

🚀 Apollo Server + Express Bootstrapping

This is the entry point of the application. In GraphQL, there is typically a single endpoint that handles all queries and mutations, commonly defined at the /graphql route.

// src/index.ts
import "reflect-metadata";
import express from "express";
import cors from "cors";
import bodyParser from "body-parser";
import { ApolloServer } from "@apollo/server";
import { expressMiddleware } from "@apollo/server/express4";
import { buildSchema } from "type-graphql";
import loadResolvers from "./loaders/loadResolvers";

async function bootstrap() {
  const resolvers = await loadResolvers();
  const schema = await buildSchema({
    resolvers: resolvers as [Function, ...Function[]],
    validate: false,
    authChecker: ({ context }) => !!context.user,
  });

  const server = new ApolloServer({ schema });
  const app = express();
  await server.start();

  app.use(
    "/graphql",
    cors(),
    bodyParser.json(),
    expressMiddleware(server, {
      context: async ({ req }) => ({ req }),
    })
  );

  app.listen(4000, () => {
    console.log("🚀 Server running at http://localhost:4000/graphql");
  });
}

bootstrap();

✅ Summary

In Part 1, we:

Defined a User model with Prisma
Set up a repository-service architecture
Built register/login logic
Defined GraphQL schema inputs & outputs
Implemented a full resolver
Configured Apollo Server

🔮 Coming in Part 2: Wallets and Transactions

We'll implement:

Wallet creation
Transfers between wallets
Transaction history

Follow the repo CashCove and stay tuned!

Thanks for reading 🙌