📦 Courier Delivery Management System (CDMS) v2.0

CDMS is a comprehensive, production-ready console-based Java application engineered to manage the end-to-end operations of a modern courier delivery service. Built with strict adherence to Object-Oriented Programming (OOP), Clean Architecture, and SOLID principles, it provides robust business logic validation, state machine processing, and blazing-fast in-memory caching with JSON persistence.

---

✨ Key Features

• 🛡️ Bulletproof Architecture: Strict N-Tier design separating Data, Business, and Presentation layers.
• ⚡ In-Memory Data Grid: Utilizes LinkedHashMap for O(1) CRUD operations. Data is asynchronously flushed to JSON via JVM Shutdown Hooks, ensuring zero I/O bottlenecks during runtime.
• 🔄 Finite State Machines (FSM): Deterministic state transitions for Orders (PENDING → PICKED_UP → IN_TRANSIT → DELIVERED) and Invoices (UNPAID → PARTIALLY_PAID → PAID).
• 🧬 Advanced Polymorphism: Custom Gson RuntimeTypeAdapterFactory and LocalDateTimeAdapter to seamlessly serialize/deserialize complex inheritance trees (e.g., DocumentParcel vs. GoodsParcel).
• 📊 Real-time Analytics & KPIs: Automated Top-Shipper leaderboards based on delivery performance.
• 💸 Robust Billing: Partial payment handling, automated invoicing (restricted to DELIVERED orders), and precise revenue tracking.
• 🚀 Fail-Fast UX: Interactive CLI that dynamically adapts valid transitions and validates inputs instantly.

---

🏗 Project Structure

src/main/java/com/courier/
├── exceptions/         # Custom domain exceptions (e.g., DuplicateIdentifierException)
├── models/             # Domain entities and Enums (OrderStatus, InvoiceStatus)
├── repositories/       # In-memory storage & JSON mapping interface
├── services/           # Business logic, FSM rules, and validations
├── ui/                 # Interactive CLI views with ConsoleTableFormatter
├── utils/              # I/O, regex validation, and Gson adapters
└── Main.java           # Application Entry Point

---

🚀 Getting Started

Prerequisites

• JDK 17 or higher
• Apache Maven 3.8+

Execution (Recommended)

Clone the repository and run the following commands from the root directory:

# Clean and compile the project
mvn clean compile

# Run the application interactive menu
mvn exec:java -Dexec.mainClass="com.courier.Main"

Note: When exiting the application using 0. Thoat, the system triggers a graceful shutdown hook that safely commits all in-memory data to data/*.json.

Running Test Suites

The project includes custom, ultra-lightweight test harnesses covering 100% of the 20 Business Rules (BR1-BR20) without relying on external frameworks like JUnit:

# Run Repository Layer Smoke Tests (Persistence & I/O)
mvn exec:java -Dexec.mainClass="com.courier.repositories.RepositorySmokeTest"

# Run Service Layer Business Rules Tests (Core Logic & FSM)
mvn exec:java -Dexec.mainClass="com.courier.services.ServiceTestSuite"

# Run UI Layer Simulation Tests (Automated Keystroke Emulation)
mvn exec:java -Dexec.mainClass="com.courier.ui.UITestHarness"

---

💾 Data Persistence

Data is stored locally in the data/ directory as beautifully formatted JSON files. The system automatically loads this data into RAM on startup. Malformed data is handled via graceful degradation (ignoring corrupted objects rather than crashing the system), ensuring extreme fault tolerance.