# Repository Overview

Welcome! This repository contains a Java-based order processing service that demonstrates how different parts of an e-commerce workflow can be wired together using dependency injection. At its core is an `OrderService` that orchestrates a typical order lifecycle — charging a payment, reserving inventory, and sending a customer notification. The code also includes a deliberate unresolved dependency (`UnresolvedInjection`) that serves as a diagnostic example for testing injection-resolution tooling. If you're exploring this codebase, you're looking at a compact, focused sample that illustrates Java EE / CDI / Spring injection patterns and service-layer design.

## Overview

This project implements the service layer of an order-processing system. The main class, `OrderService`, coordinates the end-to-end flow of placing an order by delegating to four supporting services:

- **PaymentGateway** — charges the customer's payment method.
- **InventoryService** — reserves stock for the ordered items.
- **NotificationService** — sends a confirmation notification to the customer.
- **DataSource** — provides database connections (injected but not currently used in the order flow).

All service methods are currently implemented as stubs (empty method bodies), so this code represents a structural skeleton rather than a fully functional system. It appears to be intended as a teaching example, a regression test for dependency-injection tooling, or a starting point for further development.

## Technology Stack

The codebase uses a mix of Java EE, CDI, and Spring Framework annotations for dependency injection, but does not import any well-known full-stack frameworks (such as Spring Boot, Micronaut, or Quarkus). The detected dependencies include:

| Tool / Framework | Purpose |
|---|---|
| **Java SE** | Base language and standard library |
| **JSR-330 (`javax.inject.Inject`)** | Standard dependency injection annotation |
| **EJB 3.x (`javax.ejb.EJB`)** | Enterprise Java Beans container injection |
| **Spring Framework (`org.springframework.beans.factory.annotation.Autowired`)** | Spring's dependency injection annotation |
| **JSR-250 (`javax.annotation.Resource`)** | Common resource injection annotation |

Notably, `OrderService` uses all four injection frameworks simultaneously. This mixture is unusual for a production codebase and suggests the code may have been migrated between technologies, or serves as a test fixture to validate that injection-resolution tooling can handle mixed annotation styles.

## Architecture

The system follows a simple service-oriented architecture. `OrderService` sits at the center, depending on four collaborator classes that each handle a single concern. The diagram below shows the dependency graph:

```mermaid
flowchart TD
    OS["OrderService"] --> PG["PaymentGateway"]
    OS --> IS["InventoryService"]
    OS --> NS["NotificationService"]
    OS --> DS["DataSource"]
    UI["UnresolvedInjection"] --> UT["UnknownType"]
```

### Order Flow

When a caller invokes `OrderService.placeOrder()`, the following sequential steps occur:

1. **Payment** — `PaymentGateway.charge()` is called to process the customer's payment.
2. **Inventory reservation** — `InventoryService.reserve()` locks the ordered quantities.
3. **Notification** — `NotificationService.notify()` sends a confirmation to the customer.

The flow is strictly sequential with no error handling, transaction boundary, or rollback logic. In a production system, this would typically be wrapped in a transaction or accompanied by try/catch blocks to handle failures gracefully (e.g., if the charge succeeds but inventory reservation fails, the payment would not be rolled back).

## Module Guide

### `eo.ejb.service`

This module (documented in [service.md](./eo/ejb/service.md)) defines the core order-processing backbone of the application. It contains six classes:

- **`OrderService`** — The central orchestrator. Its `placeOrder()` method executes the three-step pipeline (charge, reserve, notify). It demonstrates four different injection strategies (`@Inject`, `@EJB`, `@Autowired`, `@Resource`) across its four fields.
- **`PaymentGateway`** — A thin wrapper around external payment processing. The `charge()` method is a stub.
- **`InventoryService`** — Handles inventory reservation. The `reserve()` method is a stub.
- **`NotificationService`** — Sends customer notifications. The `notify()` method is a stub.
- **`DataSource`** — Provides database connections. The `getConnection()` method is a stub.
- **`UnresolvedInjection`** — A class with a deliberately unresolved injection reference (`UnknownType`). It is likely included as a diagnostic example for testing dependency-resolution tooling.

## Getting Started

If you are new to this codebase, here is a recommended reading order to build a mental model of the system:

1. **Read this overview** — You are here. It provides the big picture.
2. **Read `OrderService.java`** — This is the heart of the system. Understanding `placeOrder()` gives you the entire order flow in a few lines.
3. **Read the collaborator stubs** — `PaymentGateway.java`, `InventoryService.java`, `NotificationService.java`, and `DataSource.java`. Each is a single method and a few lines of code.
4. **Read the `eo.ejb.service` module page** — The [service.md](./eo/ejb/service.md) document provides a deeper dive into the injection wiring, design notes, and data model.
5. **Explore `UnresolvedInjection.java`** — This class is intentionally broken. Understanding why it references a non-existent `UnknownType` will help you see how the codebase handles unresolved dependencies.

### Key entry points

| File | Why read it |
|---|---|
| `OrderService.java` | The main orchestrator; shows the full order flow |
| `eo/ejb/service.md` | Module-level overview with design notes and wiring details |
| `PaymentGateway.java`, `InventoryService.java`, `NotificationService.java` | The three stub services that `OrderService` delegates to |

### Things to keep in mind

- **Stub methods** — Most methods have empty bodies. The code is a structural skeleton awaiting implementation.
- **Mixed injection frameworks** — `OrderService` uses four different injection annotations. This is atypical and may indicate a codebase in transition or a test fixture.
- **No error handling** — The `placeOrder()` method does not catch exceptions. Any extension should add try/catch blocks or container-managed transactions.
- **Unused dependencies** — `DataSource` is injected into `OrderService` but never called within `placeOrder()`.