A simple, open-source Transport Management System built with TypeScript, featuring a Fastify backend, React frontend, and comprehensive CRUD operations. Perfect for managing shipments, customers, and locations with a beautiful Material Design 3 interface.

Under development at the moment. I have really made this as a demo to show off our data platform capabilities at System Loco, we develop IoT devices and the supporting data and intelligence platform. We integrate with real time visibility platforms and TMS systems to provide a complete end to end solution.

Please feel free to contribute to the project, ideally with feature requests, bug reports, or documentation improvements.

I'm outlining a roadmap. It's high level. It can be ticketed up as it goes along as issues Roadmap

🌟 Live Demo: Try it now! | 📖 API Docs: View API

Note: The demo URLs above are for the project maintainer's deployment. Deploy your own instance using the Quick Demo Guide.

• Customer Management - Create, edit, and manage customer information
• Location Management - Handle warehouses, distribution centers, and retail locations
• Shipment Tracking - Complete shipment lifecycle management with status tracking
• Real-time Updates - Live data synchronization across the application
• Interactive Maps - OpenStreetMap integration for shipment visualization

• Material Design 3 - Beautiful, consistent design system
• Responsive Design - Works perfectly on desktop, tablet, and mobile
• Dark/Light Themes - Automatic theme switching based on system preferences
• Loading States - Smooth user experience with proper feedback
• Error Handling - Graceful error management and user notifications

• TypeScript - Full type safety across frontend and backend
• RESTful API - Well-documented API with Swagger/OpenAPI
• Database Migrations - Prisma-powered database management
• Repository Pattern - Clean data access layer with interface-based design
• Dependency Injection - Testable, loosely-coupled architecture
• DTO Pattern - Type-safe data transfer with validation
• Soft Delete - Data preservation with archive functionality
• Validation - Comprehensive input validation and error handling

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Database      │
│   React + Vite  │◄──►│   Fastify API   │◄──►│   PostgreSQL    │
│   TypeScript    │    │   TypeScript    │    │   Prisma ORM    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

The backend follows a clean, layered architecture with:

• Routes Layer - HTTP endpoints and request/response handling
• Repository Layer - Data access abstraction using the Repository Pattern
• Dependency Injection - Custom DI container for loose coupling and testability
• Type Safety - TypeScript interfaces (DTOs) for all data structures

Routes (HTTP)
    ↓ (uses interfaces)
Repositories (Data Access)
    ↓ (uses Prisma)
Database (PostgreSQL)

Key Patterns:

• Repository Pattern - All database operations abstracted into repository classes
• Dependency Injection - Interface-based DI container for testability
• DTO Pattern - Type-safe data transfer objects for API contracts
• Interface Segregation - Each repository has a corresponding interface

• Node.js 20+
• Docker & Docker Compose
• npm or yarn

Use the provided run script to start everything automatically:

git clone https://github.com/DominicFinn/open_tms.git
cd open_tms
npm install
./run.sh

This script will:

• ✅ Start the database in Docker
• ✅ Apply any pending database migrations
• ✅ Generate Prisma client
• ✅ Start the backend server
• ✅ Start the frontend development server

If you prefer to start services manually:

1. Clone and install dependencies:

git clone https://github.com/DominicFinn/open_tms.git
cd open_tms
npm install

2. Start the database:

docker compose up -d db

3. Apply database migrations:

cd backend
npx prisma migrate deploy
npm run prisma:generate
cd ..

4. Start development servers:

npm run dev

5. Access the application:

• Frontend: http://localhost:5173
• Backend API: http://localhost:3001
• API Documentation: http://localhost:3001/docs

1. Seed the database with sample data:

curl -X POST http://localhost:3001/api/v1/seed

2. Explore the features:

• Navigate through Customers, Locations, and Shipments
• Create, edit, and delete records
• View shipment details with interactive maps

The demo deployment includes built-in rate limiting to protect against abuse:

• 50 requests per minute per IP address
• Automatic reset every 60 seconds
• 429 status code when limit exceeded
• Clear error messages with retry information

IMPORTANT: If you are using the demo, please do not abuse the rate limit. If you need to make more requests, please contact me.

Rate limiting is implemented in the demo backend (backend/src/index-demo.ts) and configured via the Docker container. See the Dockerfile and TypeScript configuration for implementation details.

Perfect for showcasing the system to stakeholders:

📖 Hosting a Demo on GCP →

Complete production setup with monitoring and security:

📖 Production Deployment Guide →

Simple containerized deployment:

# Build and run with Docker Compose
docker compose up --build -d

# Or build individual services
docker build -t open-tms-backend ./backend
docker build -t open-tms-frontend ./frontend

• GET /api/v1/customers - List all customers
• POST /api/v1/customers - Create new customer
• GET /api/v1/customers/:id - Get customer details
• PUT /api/v1/customers/:id - Update customer
• DELETE /api/v1/customers/:id - Archive customer

• GET /api/v1/locations - List all locations
• POST /api/v1/locations - Create new location
• GET /api/v1/locations/:id - Get location details
• PUT /api/v1/locations/:id - Update location
• DELETE /api/v1/locations/:id - Archive location

• GET /api/v1/shipments - List all shipments
• POST /api/v1/shipments - Create new shipment
• GET /api/v1/shipments/:id - Get shipment details
• PUT /api/v1/shipments/:id - Update shipment
• DELETE /api/v1/shipments/:id - Archive shipment

Visit http://localhost:3001/docs for the complete Swagger/OpenAPI documentation.

• React 18 - Modern React with hooks
• TypeScript - Type-safe development
• Vite - Fast build tool and dev server
• React Router - Client-side routing
• Leaflet - Interactive maps
• Material Icons - Icon system

• Fastify - Fast and efficient web framework
• TypeScript - Type-safe server development
• Prisma - Modern database ORM
• PostgreSQL - Robust relational database
• Zod - Schema validation
• Swagger - API documentation

• Repository Pattern - Data access abstraction layer
• Dependency Injection - Custom DI container for loose coupling
• DTO Pattern - Type-safe data transfer objects
• Interface Segregation - Interface-based repository contracts
• Layered Architecture - Clear separation of routes, repositories, and services

• ESLint - Code linting
• Prettier - Code formatting
• Docker - Containerization
• GitHub Actions - CI/CD pipeline

open_tms/
├── backend/                 # Fastify API server
│   ├── src/
│   │   ├── index.ts        # Main server file
│   │   ├── routes/         # HTTP route handlers
│   │   ├── repositories/   # Data access layer (Repository Pattern)
│   │   ├── di/             # Dependency Injection container
│   │   │   ├── container.ts   # DI container implementation
│   │   │   ├── tokens.ts      # Dependency tokens
│   │   │   └── registry.ts    # Dependency registration
│   │   ├── services/       # Business logic services
│   │   └── plugins/        # Fastify plugins
│   ├── prisma/             # Database schema and migrations
│   └── Dockerfile          # Backend container
├── frontend/               # React application
│   ├── src/
│   │   ├── pages/          # Page components
│   │   ├── layout.tsx      # App layout
│   │   └── theme.css       # Material Design styles
│   └── Dockerfile          # Frontend container
├── packages/
│   └── shared/             # Shared TypeScript types
├── terraform/              # Infrastructure as Code
├── .github/workflows/      # CI/CD pipelines
└── docs/                   # Documentation

The backend follows a modular architecture with clear separation of concerns:

• HTTP endpoint definitions
• Request/response handling
• Validation using Zod schemas
• Depends on repository interfaces (not implementations)

Each repository provides:

• Interface - Contract definition (e.g., ICustomersRepository)
• DTOs - Data Transfer Objects (e.g., CreateCustomerDTO, UpdateCustomerDTO)
• Implementation - Concrete class with Prisma database operations

Example:

// Interface defines the contract
export interface ICustomersRepository {
  all(): Promise<Customer[]>;
  findById(id: string): Promise<Customer | null>;
  create(data: CreateCustomerDTO): Promise<Customer>;
  // ...
}

// Implementation uses Prisma
export class CustomersRepository implements ICustomersRepository {
  constructor(private prisma: PrismaClient) {}
  // ... method implementations
}

• Container - Simple DI container for managing dependencies
• Tokens - Symbol-based identifiers for each dependency
• Registry - Central registration of all application dependencies

Usage in routes:

const customersRepo = container.resolve<ICustomersRepository>(
  TOKENS.ICustomersRepository
);

This architecture enables:

• ✅ Testability - Easy to inject mock repositories
• ✅ Loose Coupling - Routes depend on interfaces, not concrete classes
• ✅ Flexibility - Swap implementations without changing routes
• ✅ Type Safety - Full TypeScript support with generics

The DI container makes testing straightforward:

import { container, TOKENS } from '../di';
import { ICustomersRepository } from '../repositories/CustomersRepository';

// Create a mock repository
const mockCustomersRepo: ICustomersRepository = {
  all: jest.fn().mockResolvedValue([]),
  findById: jest.fn(),
  create: jest.fn(),
  update: jest.fn(),
  archive: jest.fn(),
};

// Replace the binding for testing
container.singleton(TOKENS.ICustomersRepository)
  .toFactory(() => mockCustomersRepo);

// Now your routes will use the mock!

• Complete CRUD operations with inline editing
• Email validation and contact management
• Soft delete with archive functionality
• Real-time updates across the interface

• Comprehensive address handling with coordinates
• Geographic data support for mapping
• Warehouse and retail location management
• Address validation and formatting

• Full lifecycle management from draft to delivery
• Status tracking with visual indicators
• Interactive maps showing shipment routes
• Item management with SKU tracking
• Date management for pickup and delivery

• Material Design 3 implementation
• Responsive grid layouts that adapt to screen size
• Floating labels and smooth animations
• Loading states and error handling
• Confirmation dialogs for destructive actions

• Input validation with Zod schemas
• SQL injection protection via Prisma ORM
• CORS configuration for secure cross-origin requests
• Rate limiting for demo protection (50 requests/minute per IP)
• Environment variable management
• Soft delete for data preservation

• Fastify for high-performance API responses
• Vite for lightning-fast development and builds
• Prisma for optimized database queries
• React with efficient re-rendering
• Docker for consistent deployment environments

We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or helping with project management, your contributions make this project better for everyone.

1. Fork the repository and clone your fork
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and test them thoroughly
4. Add tests if you're adding new functionality
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to your branch: git push origin feature/amazing-feature
7. Open a Pull Request with a clear description of your changes

• 🐛 Bug Reports: Found a bug? Open an issue with detailed steps to reproduce
• ✨ Feature Requests: Have an idea? Start a discussion or open an issue
• 📝 Documentation: Help improve docs, add examples, or fix typos
• 🎨 UI/UX: Improve the design, add animations, or enhance user experience
• 🔧 Backend: Add new API endpoints, improve performance, or add features
• 🧪 Testing: Add unit tests, integration tests, or help improve test coverage
• 📊 Project Management: Help triage issues, review PRs, or organize milestones

• Follow the existing code style and patterns
• Write clear, descriptive commit messages
• Update documentation for any new features
• Ensure all tests pass before submitting a PR
• Be respectful and constructive in discussions

• 💬 Discussions: GitHub Discussions for questions and ideas
• 🐛 Issues: GitHub Issues for bug reports and feature requests
• 📖 Documentation: Check the deployment guide and API docs

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

• Documentation: Check the deployment guide
• Issues: GitHub Issues
• Discussions: GitHub Discussions

• Material Design for the beautiful design system
• Fastify team for the excellent web framework
• Prisma team for the amazing database ORM
• React team for the powerful UI library

Ready to get started? Check out the Quick Start section or deploy a demo in 5 minutes! 🚀