ParcelTracking

Modern parcel tracking API built with ASP.NET Core, Entity Framework Core, and a layered architecture across API, application, domain, and infrastructure projects.

Overview

ParcelTracking is a backend service for registering shipments, tracking parcel progress, estimating deliveries, recording delivery confirmations, and exposing operational analytics.

Highlights

• Versioned REST API via Asp.Versioning
• API key authentication using the X-Api-Key header configured in ApiKeyAuthenticationHandler
• OpenAPI support plus Scalar API reference in development from Program.cs
• PostgreSQL persistence through UseNpgsql()
• FluentValidation integration from Program.cs
• Health checks, HTTP logging, response caching, and rate limiting from Program.cs
• Seed mode for local demo data through DataSeeder.SeedAsync()
• Unit and integration tests with xUnit and Testcontainers

Architecture

The solution is organized as a clean layered application in ParcelTracking.slnx.

ParcelTracking.API             # HTTP endpoints, middleware, auth, OpenAPI
ParcelTracking.Application     # business logic, DTOs, validators, services
ParcelTracking.Domain          # entities and enums
ParcelTracking.Infrastructure  # EF Core, PostgreSQL, migrations, seeding
tests/                         # unit and integration tests

Features

Core parcel operations

• Register parcels via ParcelsController.Register()
• Retrieve parcel details via ParcelsController.GetById()
• Search parcels with filtering and pagination via ParcelsController.SearchParcels()
• Update parcel status with JSON Patch via ParcelsController.Patch()

Address management

• CRUD endpoints for shipper and recipient addresses in AddressesController

Tracking history

• Add parcel events with TrackingEventsController.Create()
• Retrieve timeline history with TrackingEventsController.GetEventHistory()

Delivery workflows

• Create delivery confirmations with ParcelsController.CreateDeliveryConfirmation()
• Calculate and recalculate delivery estimates with DeliveryEstimateController.GetEstimate() and DeliveryEstimateController.Recalculate()
• Delivery confirmation logic updates parcel state in DeliveryConfirmationService.CreateAsync()

Analytics and operations

• Parcel counts by status via AnalyticsController.GetParcelCountByStatus()
• Delivery performance reporting via AnalyticsController.GetDeliveryPerformance()
• Liveness and readiness probes exposed in Program.cs

Tech stack

• .NET 10 from ParcelTracking.API.csproj
• ASP.NET Core Web API
• Entity Framework Core
• PostgreSQL via Npgsql
• FluentValidation
• OpenAPI + Scalar
• xUnit, FluentAssertions, Moq
• DotNet.Testcontainers for integration testing

Getting started

Prerequisites

• .NET 10 SDK
• PostgreSQL 15+ running locally or remotely
• Optional: Docker for test and local database workflows

Local configuration

Development settings are defined in appsettings.Development.json.

Example development values:

• Connection string: Host=localhost;Port=5432;Database=parceltracking;Username=parcel;Password=parcel123
• API key: dev-test-key-12345

Run the API

dotnet restore
dotnet run --project ParcelTracking.API

In development, the API enables OpenAPI and Scalar through app.MapOpenApi() and app.MapScalarApiReference().

Seed demo data

Use the built-in seed mode implemented in Program.cs:

dotnet run --project ParcelTracking.API -- --seed

This populates the database with sample addresses, parcels, tracking events, content items, delivery confirmations, and parcel watchers using DataSeeder.

API access

Most endpoints require authorization through the X-Api-Key header as configured in Program.cs.

Example request header:

X-Api-Key: dev-test-key-12345

Base route

API controllers use versioned routes such as [Route("api/v{version:apiVersion}/[controller]")].

Typical base URL:

https://localhost:{port}/api/v1

Useful endpoints

Area	Endpoint	Description
Parcels	POST /api/v1/Parcels	Register a parcel
Parcels	GET /api/v1/Parcels/{id}	Get parcel details
Parcels	GET /api/v1/Parcels	Search parcels
Parcels	PATCH /api/v1/Parcels/{id}	Update status with JSON Patch
Parcels	POST /api/v1/Parcels/{trackingNumber}/delivery-confirmation	Record delivery confirmation
Addresses	GET /api/v1/Addresses	List addresses
Addresses	POST /api/v1/Addresses	Create address
Tracking	GET /api/v1/parcels/{parcelId}/events	Parcel event history
Tracking	POST /api/v1/parcels/{parcelId}/events	Add tracking event
Estimates	GET /api/v1/DeliveryEstimate?id={parcelId}	Get delivery estimate
Estimates	PUT /api/v1/DeliveryEstimate/recalculate?id={parcelId}	Recalculate estimate
Analytics	GET /api/v1/Analytics/parcel-count-by-status	Status breakdown
Analytics	GET /api/v1/Analytics/delivery-performance	Delivery performance metrics
Health	GET /health	Aggregated health report
Health	GET /health/live	Liveness probe
Health	GET /health/ready	Readiness probe

Operational concerns

The API includes several production-oriented capabilities configured in Program.cs:

• Problem details responses for errors
• Custom exception handlers
• HTTP request/response logging
• CORS policy split by environment
• Response caching for analytics and real-time endpoints
• Fixed-window rate limiting with 429 Too Many Requests

Testing

The repository contains both unit and integration tests, with additional notes in tests/README.md.

Run all tests

dotnet test ParcelTracking.slnx

Run application unit tests

dotnet test tests/ParcelTracking.Application.Tests

Run API integration tests

dotnet test tests/ParcelTracking.API.IntegrationTests

Integration tests use PostgreSQL and DotNet.Testcontainers, while unit tests use the EF Core in-memory provider in ParcelTracking.Application.Tests.csproj.

Notes

• Development secrets should not be committed; sensitive config files are ignored in .gitignore.
• Current configuration is optimized for development visibility, including SQL logging and sensitive data logging in Program.cs.
• The project already generates XML API documentation from ParcelTracking.API.csproj, which helps keep OpenAPI output descriptive.

Solution projects

• ParcelTracking.API
• ParcelTracking.Application
• ParcelTracking.Domain
• ParcelTracking.Infrastructure
• tests/ParcelTracking.API.IntegrationTests
• tests/ParcelTracking.Application.Tests