# Repository Overview

Welcome! If you're reading this, you've likely just started working with this codebase — and we're glad to have you on board. This repository implements the core service layer for an order-processing system built in Java. It coordinates the key steps of placing an order: processing payment, reserving inventory, and dispatching notifications — all orchestrated by a central `OrderService`. The code also highlights some interesting dependency-injection patterns (mixing JSR-330, EJB, and Spring annotations) and contains a known compilation issue worth flagging early.

---

## Overview

This project provides a Java-based service layer for order management. At its heart is `OrderService`, which wires together four supporting components — `PaymentGateway`, `InventoryService`, `NotificationService`, and `DataSource` — and exposes a single business entry point: `placeOrder()`. The repository is intentionally small (6 classes, 1 package), making it an ideal starting point to understand the system's architecture before diving deeper into other layers.

While the current implementations are mostly stubs (empty method bodies), the class structure and annotation choices clearly signal the intended direction: a transactional, multi-service order pipeline that charges a customer, reserves stock, and sends a confirmation — all in a single synchronous flow.

## Technology Stack

The project is written in Java and leverages several standard Java enterprise frameworks for dependency injection and resource management:

| Framework / Spec | Version | Purpose |
|---|---|---|
| JSR-330 (javax.inject) | Standard | Portable dependency injection (`@Inject`) |
| EJB 3.2 (javax.ejb) | Standard | Enterprise bean injection (`@EJB`) |
| Spring Framework | Standard | IoC injection (`@Autowired`) |
| JSR-250 (javax.annotation) | Standard | Resource injection (`@Resource`) |

No build tool configuration (Maven or Gradle) was detected in the indexed files. The project appears to be in early development — stubs and annotation wiring are in place, but the business logic is not yet implemented.

## Architecture

At a high level, `OrderService` sits at the center of the system, depending on four other services. The dependency relationships are shown below:

```mermaid
flowchart LR
    A["OrderService"] --> B["PaymentGateway"]
    A --> C["InventoryService"]
    A --> D["NotificationService"]
    A --> E["DataSource"]
```

The `placeOrder()` method runs these dependencies sequentially: charge the customer first, then reserve inventory, then send a notification. An exception in any step halts the remaining steps — there is no transactional rollback or compensation logic in the current implementation.

Additionally, `UnresolvedInjection` exists in the same package and demonstrates a class that will not compile because it references a non-existent `UnknownType` via `@Inject`.

```mermaid
flowchart TD
    A["OrderService"] --> B["@Inject PaymentGateway"]
    A --> C["@EJB InventoryService"]
    A --> D["@Autowired NotificationService"]
    A --> E["@Resource DataSource"]
    F["UnresolvedInjection"] --> G["@Inject UnknownType"]
```

Note the unusual mix of four different injection annotations within a single class. This suggests the system may be in the middle of a framework migration (e.g., from Spring to EJB), or that it was assembled from components built by different teams using different ecosystems.

## Module Guide

### `eo.ejb.service` — Core Business Services

The `eo.ejb.service` package is the only top-level module in this repository. It contains six classes that together define the order-processing workflow:

- **`OrderService`** — The central orchestrator. It injects `PaymentGateway`, `InventoryService`, `NotificationService`, and `DataSource` using four different annotation styles and exposes the `placeOrder()` method as the primary business operation. Read this class first to understand the system's entry point.
- **`PaymentGateway`** — Handles payment processing. Its `charge()` method is called as the first step in `placeOrder()`. Currently a stub.
- **`InventoryService`** — Manages inventory reservations. Injected via `@EJB`, it expects to run within an EJB application server. Its `reserve()` method is currently a stub.
- **`NotificationService`** — Dispatches notifications such as order confirmations. Injected via Spring's `@Autowired`, its `notify()` method is currently a stub.
- **`DataSource`** — Provides database connectivity. Injected via JSR-250's `@Resource`, its `getConnection()` method is currently a stub.
- **`UnresolvedInjection`** — A class with a known compilation error. It references a non-existent `UnknownType` via `@Inject` and serves as a useful cautionary example for dependency-injection issues.

## Getting Started

If you're new to this codebase, here's the recommended reading order:

1. **Start with `OrderService.java`** — This is the entry point and orchestrator. It ties everything together and its `placeOrder()` method defines the core business flow.
2. **Read the four supporting services** (`PaymentGateway`, `InventoryService`, `NotificationService`, `DataSource`) — Each is a thin stub, so you can read them in any order. They define the contract that `OrderService` expects.
3. **Review `UnresolvedInjection.java`** — Pay attention to this class as it highlights a known compilation issue. If you encounter injection errors, this is a good place to look for patterns to avoid.
4. **Check the module detail page** — The [`service` module page](eo/ejb/service.md) provides an in-depth breakdown of the order-placement flow, dependency injection details, and notes for developers.

## Notes for Developers

- **All service methods are currently stubs.** The bodies of `charge()`, `reserve()`, `notify()`, and `getConnection()` are empty. Implementation is needed before these services can be used in production.
- **The injection annotation mix requires both an EJB container and Spring on the classpath.** If you remove Spring from the classpath, `@Autowired` will become a compile-time error.
- **`UnresolvedInjection` will not compile.** The `UnknownType` reference does not exist. Resolve or remove this class before merging changes.
- **No error handling in `placeOrder()`.** If any step throws, subsequent steps are skipped. Consider adding transactional boundaries and compensation logic before production use.
- **No idempotency guarantees.** Calling `placeOrder()` twice will charge and reserve twice. An idempotency key or guard should be added before production use.