Skip to content

okings69/port_performance_analyzer

BranchesTags

Repository files navigation

Port Performance Analyzer

A full-stack enterprise-style platform for monitoring, evaluating, and comparing the operational performance of maritime ports and dry ports.

The project combines a .NET 8 Web API, a React + Vite + TypeScript frontend, PostgreSQL, and JWT authentication in a clean, layered architecture designed for maintainability, extensibility, and real-world portfolio presentation.

Overview

Port Performance Analyzer helps administrators and analysts manage ports, define performance indicators, record operational measurements, calculate weighted scores, rank ports by period, and visualize results through dashboards and comparison charts.

It is built as a structured, enterprise-oriented application with a strong focus on:

  • clear separation of concerns
  • practical analytics workflows
  • role-based access control
  • clean API/frontend integration

Features

  • JWT-based authentication and role-based authorization
  • User roles: Admin, Analyst, Viewer
  • CRUD management for ports
  • CRUD management for performance indicators
  • CRUD management for measurements
  • Weighted performance score calculation by period
  • Port ranking and comparison by selected period
  • Dashboard with KPIs and charts
  • Seeded sample data for quick local evaluation
  • Swagger/OpenAPI support for API exploration
  • Frontend language support with French UI translation
  • Docker support included, while remaining fully runnable locally without Docker

Architecture

The solution follows a layered architecture inspired by Clean Architecture principles.

Backend layers

  • PortPerformanceAnalyzer.Api
    • API entry point, controllers, middleware, configuration, Swagger, authentication wiring
  • PortPerformanceAnalyzer.Application
    • DTOs, interfaces, mappings, shared application contracts
  • PortPerformanceAnalyzer.Domain
    • Core entities, enums, and domain primitives
  • PortPerformanceAnalyzer.Infrastructure
    • EF Core, PostgreSQL integration, migrations, seed data, authentication helpers, service implementations

Frontend structure

  • api: HTTP client configuration
  • components: reusable UI and chart components
  • context: auth, toast, and i18n state
  • hooks: custom React hooks
  • layouts: application layout and sidebar
  • pages: feature pages
  • services: API wrappers by domain
  • types: shared frontend types
  • utils: formatting and helper utilities

Project Structure

port_performance_analyzer
├── backend
│   ├── PortPerformanceAnalyzer.Api
│   │   ├── Controllers
│   │   ├── Extensions
│   │   ├── Middleware
│   │   ├── Properties
│   │   ├── Program.cs
│   │   └── appsettings.json
│   ├── PortPerformanceAnalyzer.Application
│   │   ├── Common
│   │   ├── DTOs
│   │   ├── Interfaces
│   │   ├── Mappings
│   │   └── Validators
│   ├── PortPerformanceAnalyzer.Domain
│   │   ├── Common
│   │   ├── Entities
│   │   └── Enums
│   └── PortPerformanceAnalyzer.Infrastructure
│       ├── Auth
│       ├── Data
│       │   └── Migrations
│       └── Services
├── frontend
│   ├── public
│   ├── src
│   │   ├── api
│   │   ├── components
│   │   ├── context
│   │   ├── hooks
│   │   ├── layouts
│   │   ├── pages
│   │   ├── services
│   │   ├── types
│   │   └── utils
│   ├── package.json
│   └── vite.config.ts
├── docker-compose.yml
├── NuGet.Config
└── README.md

Tech Stack

Backend

  • ASP.NET Core Web API (.NET 8)
  • Entity Framework Core
  • Npgsql Entity Framework Core Provider
  • JWT Bearer Authentication
  • BCrypt password hashing
  • Swagger / OpenAPI

Frontend

  • React
  • Vite
  • TypeScript
  • Tailwind CSS
  • Recharts
  • Axios

Database & DevOps

  • PostgreSQL
  • Docker / Docker Compose

Prerequisites

Before running the project locally, make sure you have:

  • .NET SDK 8+
  • Node.js 20+
  • npm
  • PostgreSQL 16+
  • Docker Desktop (optional)

Local Setup

1. Clone the repository

git clone <your-repository-url>
cd port_performance_analyzer

2. Configure PostgreSQL

Create a local PostgreSQL database named:

port_performance_analyzer

Make sure you know the local PostgreSQL username and password you want to use.

3. Restore and build the backend

cd D:\Oks\port_performance_analyzer

$env:DOTNET_ROLL_FORWARD="Major"
$env:ConnectionStrings__DefaultConnection="Host=localhost;Port=5432;Database=port_performance_analyzer;Username=postgres;Password=YOUR_PASSWORD;Include Error Detail=true"
$env:Jwt__Issuer="PortPerformanceAnalyzer"
$env:Jwt__Audience="PortPerformanceAnalyzer.Client"
$env:Jwt__SecretKey="CHANGE_THIS_TO_A_LONG_RANDOM_SECRET_KEY_2026"

dotnet restore .\backend\PortPerformanceAnalyzer.Api\PortPerformanceAnalyzer.Api.csproj --configfile .\NuGet.Config
dotnet build .\backend\PortPerformanceAnalyzer.Api\PortPerformanceAnalyzer.Api.csproj

4. Apply database migrations

dotnet ef database update --project .\backend\PortPerformanceAnalyzer.Infrastructure --startup-project .\backend\PortPerformanceAnalyzer.Api

5. Run the backend

dotnet run --project .\backend\PortPerformanceAnalyzer.Api

Backend URL:

http://localhost:8080

6. Run the frontend

In a separate terminal:

cd D:\Oks\port_performance_analyzer\frontend
$env:VITE_API_BASE_URL="http://localhost:8080/api"
npm.cmd install
npm.cmd run dev

Frontend URL:

http://localhost:5173

Default Users

The application seeds a few accounts for local testing.

Role Email Password
Admin admin@portanalyzer.local Admin@123
Analyst analyst@portanalyzer.local Analyst@123
Viewer viewer@portanalyzer.local Viewer@123

API Documentation

Swagger is enabled in development.

Open:

http://localhost:8080/swagger

You can use it to:

  • authenticate
  • inspect available endpoints
  • test protected routes
  • validate request/response payloads

Example Endpoints

POST /api/auth/register
POST /api/auth/login

GET /api/ports
POST /api/ports

GET /api/indicators
POST /api/indicators

GET /api/measurements
POST /api/measurements

POST /api/scores/calculate/{portId}?period=2026-Q1
GET /api/reports/rankings?period=2026-Q1
GET /api/dashboard/summary?period=2026-Q1

Core Concepts

Indicators

Indicators define the performance dimensions used to evaluate a port.

Examples include:

  • cargo throughput
  • average vessel turnaround time
  • berth / terminal utilization
  • on-time dispatch rate

Each indicator has:

  • a name and description
  • a unit
  • a weight
  • a direction rule:
    • higher is better
    • lower is better

Measurements

Measurements are the raw operational values recorded for a specific:

  • port
  • indicator
  • period
  • measurement date

They represent the underlying operational data that feeds the analytics layer.

Scores

Scores are calculated from recorded measurements using weighted normalization rules.

The current scoring implementation:

  • uses indicator weights
  • handles both positive and inverse indicators
  • calculates a global score for a selected period
  • stores score history for ranking and dashboard use

Rankings

Rankings order ports by calculated score for a given period.

They are used to:

  • compare ports quickly
  • identify stronger and weaker performers
  • support dashboard analytics and reporting views

Testing

The project supports practical testing across backend, frontend, and full user workflows.

Functional testing

The main business flows can be tested through the UI and Swagger:

  • login
  • port creation
  • indicator creation
  • measurement recording
  • score calculation
  • ranking updates
  • dashboard visualization

End-to-end testing

A typical end-to-end local workflow is:

  1. start PostgreSQL
  2. run dotnet ef database update
  3. run dotnet run
  4. run npm run dev
  5. sign in with a seeded user
  6. add measurements
  7. calculate a score
  8. verify ranking and dashboard results

Authentication testing

Authentication can be validated through:

  • POST /api/auth/login
  • JWT-protected Swagger routes
  • role-based UI access and permissions

Validation testing

The API includes request validation for:

  • required fields
  • numeric constraints
  • paging parameters
  • domain-specific request formats such as periods

Build verification

The current codebase has been validated with:

  • dotnet build
  • npm run build

Docker Setup

Docker support is included, although the project is fully runnable without Docker.

Run the full stack with:

docker compose up --build

Default container endpoints:

  • Frontend: http://localhost:5173
  • Backend API: http://localhost:8080
  • PostgreSQL: localhost:5432

If Docker is not installed on your machine, use the Local Setup section above.

Future Improvements

  • Export reports (Excel / PDF)
  • Advanced analytics
  • Real-time data ingestion
  • Multi-tenant support
  • CI/CD pipeline

Author

Project maintained by the repository owner.

License

No license has been specified yet. If this project is intended for public reuse, adding an explicit license such as MIT is recommended.

port_performance_analyzer

Développement d'une version simplifiée de la plateforme d'évaluation de performance des ports secs/maritimes

c69c9b08dba7f1bd1c6654478b71460a70edb8a1

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages