Gestify

Gestify is a .NET 8 modular backend solution for personal finance management. It combines account management, wallet transactions, user onboarding, authentication, and MPesa-powered payments in a layered architecture built around Domain-Driven Design and CQRS.

Overview

Gestify exposes a versioned API for:

• user registration and login
• account creation and management
• wallet top-ups and remittances
• user goal configuration
• payment flows backed by the MPesa gateway integration

The solution is organized into separate projects for API, application, domain, infrastructure, shared kernel, anti-corruption, and automated tests.

Running locally

With Docker Compose

The repository includes Docker Compose services for the API, PostgreSQL, Keycloak, Seq, and Redis.

docker compose up --build

The API will be available at:

• http://localhost:5000
• https://localhost:5001

The infrastructure services are exposed as:

• PostgreSQL: localhost:5432
• Keycloak: http://localhost:18080
• Seq UI: http://localhost:8081
• Redis: localhost:6379

With dotnet directly

If you prefer to run the API without containers, first ensure the required services are reachable and then start the API:

dotnet restore
dotnet run --project src/Gestify.Api

The application uses development configuration values for PostgreSQL, Redis, Serilog/Seq, and Keycloak inside the API project.

Technology stack

• .NET 8 / ASP.NET Core
• Entity Framework Core + Npgsql
• Dapper for data access helpers
• MediatR for CQRS
• FluentValidation for request validation
• Serilog with Seq logging
• PostgreSQL, Redis, and Keycloak
• Swagger / OpenAPI and health checks
• Docker Compose for local infrastructure

API surface

All endpoints are exposed under the versioned route prefix /api/v1.

Users

• POST /api/v1/users/register
• POST /api/v1/users/login
• GET /api/v1/users/me
• PATCH /api/v1/users/me/goal

Accounts

• GET /api/v1/accounts
• GET /api/v1/accounts/{number}
• PUT /api/v1/accounts/{number}

Transactions

• GET /api/v1/transactions
• GET /api/v1/transactions/{id}
• POST /api/v1/transactions/top-up
• POST /api/v1/transactions/remittance

Architecture notes

The solution follows a layered, DDD-oriented design:

• Domain: aggregates, value objects, domain services, and domain events
• Application: commands, queries, handlers, validators, and pipeline behaviors
• Infrastructure: EF Core, repositories, caching, authentication, authorization, and external integrations
• API: endpoint definitions, request/response DTOs, and presentation concerns

The application layer uses CQRS patterns with MediatR. Commands and queries are separated, and cross-cutting concerns such as logging, validation, and caching are implemented as pipeline behaviors.

Testing coverage

The solution includes multiple test layers:

• Unit tests for domain and application behavior
• Integration tests for application workflows against test infrastructure
• Functional tests for the HTTP API using WebApplicationFactory and containerized dependencies
• Architecture tests to enforce project boundaries and layering rules

Typical commands:

dotnet test

MPesa integration

MPesa payments are integrated through the anti-corruption layer in the Gestify.AntiCorruption project. The solution uses the MPesa SDK and wires the MPesa client through dependency injection.

The integration currently supports:

• wallet top-up flows
• remittance flows
• payment gateway abstraction through the domain-level IPaymentGateway

Configuration is sourced from the Mpesa section in the API configuration, including API key, public key, service provider code, initiator identifier, and security credential.

Development notes

Swagger

Swagger and Swagger UI are enabled in development mode. Open:

• http://localhost:5000/swagger
• https://localhost:5001/swagger

Health checks

The API exposes a health endpoint at:

• http://localhost:5000/health

Logging and observability

• Serilog is configured for structured logging
• Request logging is enabled in the API pipeline
• Seq is included in Docker Compose for log aggregation at http://localhost:8081

Local infrastructure services

The default development stack provisions:

• PostgreSQL for the main database
• Redis for caching
• Keycloak for identity and authentication
• Seq for log collection

Project structure

• src/Gestify.Api - HTTP API and endpoint registration
• src/Gestify.Application - commands, queries, validation, and MediatR behaviors
• src/Gestify.Domain - business domain, entities, value objects, and rules
• src/Gestify.Infrastructure - EF Core, repositories, auth, caching, and health checks
• src/Gestify.AntiCorruption - external system adapters such as MPesa
• tests - unit, integration, functional, and architecture test projects