Budget Orb

Budget Orb is a personal finance management application built with .NET 10 and ASP.NET Core MVC. It helps users track their income and expenses by organizing transactions into categories, with full CRUD operations, pagination, sorting, and filtering capabilities.

This application demonstrates modern .NET development practices including Clean Architecture, Entity Framework Core for data access, and a responsive MVC frontend with server-side rendering.

Table of Contents

• Budget Orb
  • Technologies
  • Installation
    • Prerequisites
    • Running the Application
  • Features
    • Category Management
    • Transaction Management
    • Pagination
    • Sorting
    • Filtering and Search
    • Database Initialization
    • Database Seeding
    • Clean Architecture
    • Error Handling
  • Contributing
  • License
  • Contact

Technologies

• .NET 10
• ASP.NET Core MVC
• Entity Framework Core 10
• SQL Server
• Bogus

Installation

Prerequisites

• .NET 10 SDK
• SQL Server or SQL Server Express LocalDB (included with Visual Studio)

Running the Application

1. Clone the repository

   • using HTTPS
     • https://github.com/nwdorian/BudgetOrb.git
   • using SSH
     • git@github.com:nwdorian/BudgetOrb.git
   • using GitHub CLI
     • gh repo clone nwdorian/BudgetOrb

2. Configure database connection (optional)

   • Open src/BudgetOrb.Web/appsettings.json
   • Modify the ConnectionStrings:Default value if needed
   • Default uses LocalDB: Data Source=(localdb)\MSSQLLocalDB; Initial Catalog=BudgetOrbDb; Integrated Security=SSPI

3. Build and run from project root folder

   dotnet run --project ./src/BudgetOrb.Web

4. Access the application

   • Open browser to https://localhost:5243 (or port shown in console)

Features

Category Management

• Create, read, update, and delete categories
• Unique category name validation
• View all categories with transaction count and total amount spent
• Modal-based workflows

Transaction Management

• Create, read, update, and delete transactions
• Associate transactions with categories
• Track amount, date, and optional comment for each transaction
• Form validation with error messages
• Modal-based workflows

Pagination

• Configurable page sizes: 10, 25, or 50 items per page
• Navigation controls: Previous, Next, Active page indicator
• Persistent page state during filtering

Sorting

• Sort by Amount, Date, Comment, or Category
• Ascending and descending order support

Filtering and Search

• Text Search: Search across transaction comments
• Category Filter: Dropdown to filter by specific category
• Date Range: Filter transactions by start and end dates
• Combined filtering with sorting and pagination

Database Initialization

• Automatic database migrations on application startup
• EF Core 10 with SQL Server provider
• Connection string configuration via appsettings.json
• Supports LocalDB for development

Database Seeding

• Automatic seeding of fake data in non-production environments
• Generates realistic categories and transactions using Bogus
• Creates 100 transactions per category for testing
• Deterministic seed data for reproducible testing

Clean Architecture

Organized into four distinct layers:

• Domain: Core business entities
• Application: Business logic, services, and contracts
• Infrastructure: Data access with EF Core, database context, and seeding
• Web: MVC controllers, view models, and Razor views

Error Handling

• Centralized error handling middleware
• Custom Result pattern for operation outcomes
• Validation error display in modals
• HTTP status code appropriate responses

Contributing

Contributions are welcome! Please fork the repository and create a pull request with your changes. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For any questions or feedback, please open an issue.