# Getting Started

> I just joined the team — where do I start reading?

This guide helps new engineers navigate this codebase quickly. Read on to understand what the project does, where the entry points are, and in what order to explore the documentation.

---

## What This Project Does

This repository implements the core service layer for an order-processing system written in Java. At its center is `OrderService`, which orchestrates the key steps of placing an order: charging a payment gateway, reserving inventory, and dispatching a notification. The project also highlights interesting dependency-injection patterns — mixing JSR-330, EJB, and Spring annotations — and contains a known compilation issue (`UnresolvedInjection`) worth flagging early.

## Recommended Reading Order

New team members should read the wiki pages in this order:

1. **[Repository Overview](overview.md)** — High-level project summary, architecture, and technology stack.
2. **[Module: eo.ejb.service](eo/ejb/service.md)** — Detailed breakdown of every class, its dependencies, and notes for developers.
3. **This guide** — Quick-reference on structure, entry points, and common patterns.

After that, dive into the source files themselves (suggested order below).

## Key Entry Points

### Start with `OrderService`

`OrderService` (`service/OrderService.java`) is the central orchestrator and the best place to begin. It exposes the `placeOrder()` method — the primary business entry point — and wires together four supporting components using four different injection styles:

| Annotation | Source | Field |
|---|---|---|
| `@Inject` | JSR-330 | `PaymentGateway` |
| `@EJB` | EJB 3.2 | `InventoryService` |
| `@Autowired` | Spring | `NotificationService` |
| `@Resource` | JSR-250 | `DataSource` |

Understanding `placeOrder()` gives you the complete business flow: charge, reserve, notify — in that order.

### Then explore the supporting services

Each of these classes is currently a thin stub (empty method bodies), so they're quick to read:

- **[PaymentGateway](service/ PaymentGateway.java)** — Handles `charge()`, the first step in the order pipeline.
- **[InventoryService](service/InventoryService.java)** — Manages `reserve()`, called after payment succeeds.
- **[NotificationService](service/NotificationService.java)** — Dispatches `notify()` as the final confirmation step.
- **[DataSource](service/DataSource.java)** — Provides `getConnection()` for database access.

### Finally, review `UnresolvedInjection`

**[UnresolvedInjection](service/UnresolvedInjection.java)** references a non-existent `UnknownType` and will not compile. Study it to understand the kind of `@Inject` errors the team should look for.

## Project Structure

The repository is intentionally small: one package, six classes.

```
.
├── DataSource.java
├── InventoryService.java
├── NotificationService.java
├── OrderService.java          ← read first
├── PaymentGateway.java
├── UnresolvedInjection.java
└── .codewiki/
    ├── overview.md            ← high-level docs
    ├── tree.json              ← repository index
    └── eo/ejb/service.md      ← module detail page
```

Everything lives in the `eo.ejb.service` package. There are no sub-modules, no tests, and no build tool configuration (Maven/Gradle) detected in the indexed files. The project is in early development — stubs and annotation wiring are in place, but the business logic is not yet implemented.

## Architecture

`OrderService` depends on four services. Here's a simplified dependency graph:

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

The `placeOrder()` method runs these dependencies sequentially. An exception in any step halts the remaining steps — there is no transactional rollback or compensation logic in the current implementation.

## Configuration

This project is in early development and has no build tool configuration yet. Key points:

- **Dependency injection requires multiple frameworks on the classpath.** The project mixes JSR-330 (`javax.inject`), EJB 3.2 (`javax.ejb`), Spring (`org.springframework`), and JSR-250 (`javax.annotation`). If you remove Spring from the classpath, `@Autowired` becomes a compile-time error.
- **`InventoryService` is injected via `@EJB`.** It expects to run within an EJB application server (e.g., WildFly, GlassFish).
- **No external config files** (properties, YAML, XML) were detected. The `DataSource` is injected at runtime via `@Resource`.

## Common Patterns

### Dependency injection annotation mix

The same class (`OrderService`) uses four different injection annotations. This suggests the system may be in the middle of a framework migration (e.g., from Spring to EJB) or was assembled from components built by different teams. When you see unfamiliar injection annotations in this codebase, check whether multiple frameworks are needed at runtime.

### Sequential orchestration

`placeOrder()` calls its dependencies one after another with no parallelism:

```java
paymentGateway.charge();
inventory.reserve();
notificationService.notify();
```

If an exception occurs in any step, the remaining steps are silently skipped. Consider adding transactional boundaries and compensation logic before production use.

### Empty stubs

All service methods (`charge()`, `reserve()`, `notify()`, `getConnection()`) have empty bodies. Implementation is needed before these services can process real orders. Look for `TODO` or `FIXME` comments as work progresses.

### Compilation guard

`UnresolvedInjection` serves as a living example of what happens when a DI container cannot resolve a dependency. If you encounter injection errors, check for patterns matching this class first.

---

## Quick Reference

| Concern | Where to look |
|---|---|
| Business entry point | `OrderService.placeOrder()` |
| Payment flow | `PaymentGateway.charge()` |
| Inventory reservation | `InventoryService.reserve()` |
| Notifications | `NotificationService.notify()` |
| Database access | `DataSource.getConnection()` |
| Known compile error | `UnresolvedInjection` |
| Architecture overview | [overview.md](overview.md) |
| Module details | [eo/ejb/service.md](eo/ejb/service.md) |

---

## Notes for Developers

- **All service methods are stubs.** The bodies are empty — implementation is needed.
- **No error handling in `placeOrder()`.** Exceptions in any step halt the flow.
- **No idempotency guarantees.** Calling `placeOrder()` twice charges and reserves twice.
- **`UnresolvedInjection` will not compile.** Resolve or remove it before merging.