Field Expense Tracker

Content

• Project Overview
• Project Architecture and Model Relationships
• Prerequisites
• Setup & Run
• Basic Usage
• API Documentation

Project Overview

Field Expense Tracker is a .NET-based web API designed to let field personnel submit expense claims in real time, enable administrators to approve or reject those claims and simulate payments, and provide detailed daily, weekly and monthly spending reports.

Key features:

• JWT-based authentication and role-based authorization (Admin and Personnel)
• Expense create, read, update and delete operations with receipt upload support
• Approval and rejection workflows, including a rejection reason field
• Background payment simulation using in-memory .NET Channel
• Report generation via Dapper and SQL views (daily, weekly, monthly, per-user, status summaries)
• Admin-only endpoints for user and category management
• Swagger UI with XML comments integration
• Optional Redis caching for high-performance scenarios

Technology Stack

• .NET 8.0 Web API
• Entity Framework Core (Code-First)
• Dapper
• Microsoft SQL Server or PostgreSQL
• JWT Bearer Authentication
• Swashbuckle (Swagger)

Project Architecture and Model Relationships

Project follows a clean, layered architecture with four main projects under a single solution file.

FieldExpenseTracker/
├─ FieldExpenseTracker.sln              
├─ FieldExpenseTracker.Domain/          // Domain layer: entities, enums, interfaces
│  ├─ Entities/                         // Entity classes (User, Expense, etc.)
│  ├─ Enums/                            // Enumeration types (RoleType, ExpenseStatus, PaymentMethod)
│  └─ Interfaces/                       // IRepository, IUnitOfWork, IExpenseRepository, etc.
├─ FieldExpenseTracker.Application/     // Application layer: DTOs, services, mappings, validations
│  ├─ DTOs/                             // Data Transfer Objects for API requests/responses
│  ├─ Services/                         // Business logic services
│  │  ├─ Interfaces/                    // IExpenseService, IAuthService, etc.
│  │  └─ Implementations/               // ExpenseService, AuthService, ReportService, etc.
│  ├─ Mappings/                         // AutoMapper profiles
│  └─ Validations/                      // FluentValidation rules
├─ FieldExpenseTracker.Infrastructure/  // Infrastructure layer: EF Core, repositories, configurations
│  ├─ Data/                             // ExpenseDbContext and EF migrations
│  ├─ Configurations/                   // EntityTypeConfiguration & seed data
│  └─ Repositories/                     // Repository implementations
└─ FieldExpenseTracker.Api/             // Web API project: controllers, middleware, hosting
   ├─ Controllers/                      // API endpoints (Expense, Reports, Users, etc.)
   ├─ Middlewares/                      // Exception handling, logging, etc.
   ├─ Services/                         // Background services (PaymentSimulatorService)
   ├─ Startup.cs                        // DI, middleware, Swagger configuration
   └─ Program.cs                        // Application entry point

Model Relationships

• A User can have many Expenses (one-to-many). Each Expense.UserId FK points to Users.Id.
• An ExpenseCategory can have many Expenses (one-to-many). Each Expense.CategoryId FK points to ExpenseCategories.Id.
• An Expense may (optionally) have one Payment (one-to-one). Payment.ExpenseId is a unique FK pointing back to Expense.Id, and the cascade delete ensures that deleting an Expense also removes its Payment.
• Enum properties (RoleType on User, ExpenseStatus and PaymentMethod on Expense) are all persisted as integers in the database for efficiency and version-tolerant mapping.

Database Views for Reporting

We create seven SQL views (daily, weekly, monthly spend; user spend at each period; status summary) directly in the database via migrations or on startup, and then our Dapper-based ReportService simply selects from those views for lightning-fast, aggregated results.

Prerequisites

• .NET 8 SDK
• Docker (recommended) or local SQL Server / PostgreSQL
• (Optional) DBeaver or Azure Data Studio for DB inspection

Setup & Run

0. Install the .NET 8 SDK (or later), and have either SQL Server or PostgreSQL running locally (or in Docker) with an empty database ready.

1. Clone the repo:

   git clone https://github.com/your-org/field-expense-tracker.git
   cd field-expense-tracker

2. Configure appsettings.json: Open the file named appsettings.json in the Api project and:

   • Set ActiveDatabase to either Mssql or Postgres
   • Update the ConnectionStrings section for your database
   • Update the JwtConfig section with your token settings

3. Apply migrations & seed data: Before you launch the API, you must create your database schema and initial seed data.

   cd FieldExpenseTracker.Infrastructure
   dotnet ef database update --startup-project ../FieldExpenseTracker.Api

   That command will create all tables, insert the admin and sample users, expense categories and two test expenses, and also build all the report views automatically—no manual SQL editing. Next you need a folder for receipt images: from the Api folder, create a directory called wwwroot/uploads. The code will drop uploaded files there and serve them statically.

4. Run the API:

   cd ../FieldExpenseTracker.Api
   dotnet run

5. Browse Swagger at https://localhost:5257/index.html or http://localhost:5257.

Basic Usage

1. Authenticate via POST /api/auth/login to receive a JWT token.
   • Admin :

        {
           "email": "admin@test.com",
           "password": "admin123"
         }

   • Normal User :

        {
           "email": "john@test.com",
           "password": "user123"
         }

2. Include the token in an HTTP header for secured endpoints:
   • Authorization: Bearer
3. Expenses:
   • Create: POST /api/expenses (multipart/form-data with ReceiptImage)
   • List, filter, update, delete via /api/expenses endpoints
   • Approve or reject an expense as an admin via /api/expenses/{id}/approve or /reject
4. Reports
   • GET /api/reports/summary, /personnel-summary, /status-summary (admin only)
   • GET /api/reports/my-summary (authenticated user)
5. Categories and Users (admin only)
   • Manage via /api/expensecategories and /api/users endpoints
6. Payments
   • View and manage simulated payment records under /api/payments

API Documentation

• Swagger UI provides all endpoints, request/response schemas, and supports JWT auth.
• Checkout postman : postman link