AfriHaul

A logistics platform tackling freight fragmentation across South Africa and the SADC region. Built with landmark-based addressing in mind (for areas without formal street addresses), shipment creation, and carrier matching — designed for the African logistics context from the ground up. Currently in beta.

---

Features

• Shipment management — create shipments, list pending shipments
• Carrier matching — find available carriers by country, register new carriers
• Clean Architecture — strict separation between Domain, Application, Infrastructure, and API layers
• CQRS with MediatR — commands and queries are isolated per feature (Features/Shipments/Commands, Features/Shipments/Queries)
• Validation pipeline — FluentValidation wired into the Application layer
• Swagger/OpenAPI — auto-generated interactive API docs via Swashbuckle
• Angular frontend — server-side rendered (SSR) Angular 21 app styled with Tailwind CSS

Tech Stack

Backend (AfriHaul.API, .Application, .Domain, .Infrastructure)

Layer	Technology
Runtime	.NET 10
API	ASP.NET Core Web API
Architecture	Clean Architecture (Domain / Application / Infrastructure / API)
CQRS	MediatR
Validation	FluentValidation
ORM	Entity Framework Core 9
Database (current)	SQLite (afrihaul.db, local file)
API Docs	Swashbuckle (Swagger UI)

Frontend (afrihaul-frontend)

Layer	Technology
Framework	Angular 21 (standalone, with SSR via @angular/ssr)
Styling	Tailwind CSS 3
Language	TypeScript
Server	Express (for SSR)

Note on the database: appsettings.json currently lists a PostgreSQL connection string, but the actual wiring in AfriHaul.Infrastructure/DependencyInjection.cs uses SQLite (Data Source=afrihaul.db) — the Postgres string is unused leftover config. The plan (per the frontend's own project description) is SQLite → PostgreSQL as the project matures.

⚠️ Security Note

AfriHaul.API/appsettings.json currently has a real local database password committed to the repo (in the unused Postgres connection string) and the SQLite file afrihaul.db is also tracked. Before making this repo public or continuing development:

• Remove the hardcoded password from appsettings.json, and move secrets to appsettings.Development.json (git-ignored) or .NET User Secrets
• Add *.db and appsettings.Development.json to .gitignore
• Rotate the exposed password if it's reused anywhere else

Prerequisites

• .NET 10 SDK
• Node.js 20 or later (for the Angular frontend)
• Angular CLI: npm install -g @angular/cli
• Entity Framework Core tools: dotnet tool install --global dotnet-ef

Installation

Backend

# 1. Clone the repository
git clone https://github.com/phiwakonkem/AfriHaul.git
cd AfriHaul

# 2. Restore .NET dependencies
dotnet restore

# 3. Apply EF Core migrations (creates/updates afrihaul.db)
cd AfriHaul.API
dotnet ef database update

# 4. Run the API
dotnet run

The API will start on the port shown in the console (check AfriHaul.API/Properties/launchSettings.json), with Swagger UI available at /swagger in development mode.

Frontend

# In a separate terminal, from the repo root
cd afrihaul-frontend

# 1. Install dependencies
npm install

# 2. Start the dev server
npm start

The Angular app will be running at http://localhost:4200.

Project Structure

AfriHaul/
├── AfriHaul.API/              # ASP.NET Core Web API, controllers, Program.cs
│   └── Controllers/
│       ├── ShipmentsController.cs   # GET /api/shipments/pending, POST /api/shipments
│       └── CarriersController.cs    # GET /api/carriers/available/{country}, POST /api/carriers
├── AfriHaul.Application/      # CQRS commands/queries, validators, DI setup
│   └── Features/Shipments/{Commands,Queries}
├── AfriHaul.Domain/           # Entities: Shipment, Carrier, Fleet, Route, Shipper
├── AfriHaul.Infrastructure/   # EF Core DbContext, migrations, UnitOfWork
├── AfriHaul.slnx              # Solution file
└── afrihaul-frontend/         # Angular 21 SSR frontend

API Endpoints

Method	Endpoint	Description
GET	/api/shipments/pending	List all pending shipments
POST	/api/shipments	Create a new shipment
GET	/api/carriers/available/{country}	List carriers available in a given country
POST	/api/carriers	Register a new carrier

Full interactive docs are available via Swagger UI when running the API locally in Development mode.

Roadmap

• Migrate from SQLite to PostgreSQL for production
• Move secrets out of appsettings.json into environment-based configuration
• Add authentication/authorization for shippers vs. carriers
• Route optimisation and fleet tracking
• Landmark-based addressing UI for areas without formal street addresses

Author

Phiwakonke Mthethwa — Full-Stack Developer, South Africa GitHub · LinkedIn · phiwakonkem@gmail.com

License

MIT