# Getting Started

## What This Project Does

This codebase is a small Java application organized around users, products, and orders. It uses a simple controller-service-model structure with a few shared utilities, so the flow is easy to follow and the classes stay focused on one responsibility. Most of the behavior is in-memory and intentionally lightweight, which makes this a good repository for understanding the application shape before adding features.

## Recommended Reading Order

1. [`com.example.Application`](../src/com/example/Application.java) — start here to see how the app is assembled and what runs first.
2. [`com.example.controller.UserController`](../src/com/example/controller/UserController.java) and [`com.example.controller.ProductController`](../src/com/example/controller/ProductController.java) — read these next to understand the entry points into the business logic.
3. [`com.example.service.UserService`](../src/com/example/service/UserService.java), [`com.example.service.ProductService`](../src/com/example/service/ProductService.java), and [`com.example.service.OrderService`](../src/com/example/service/OrderService.java) — these contain the main behavior.
4. [`com.example.model.User`](../src/com/example/model/User.java), [`com.example.model.Product`](../src/com/example/model/Product.java), and [`com.example.model.Order`](../src/com/example/model/Order.java) — use these to understand the data passed through the app.
5. [`com.example.util.ValidationUtil`](../src/com/example/util/ValidationUtil.java) — finish here to see the shared validation helpers.

If you want a broader overview of the package layout, read [`com.example`](../.codewiki/com/example.md) after the file-level walkthrough.

## Key Entry Points

The most important classes to understand first are:

- [`Application`](../src/com/example/Application.java) — the top-level bootstrap class.
- [`HelloWorld`](../src/com/example/HelloWorld.java) — a minimal standalone example of how the package can be executed.
- [`UserController`](../src/com/example/controller/UserController.java) — shows the user flow from controller into service.
- [`ProductController`](../src/com/example/controller/ProductController.java) — shows the product lookup/listing flow.
- [`UserService`](../src/com/example/service/UserService.java) — creates and stores users with basic validation.
- [`ProductService`](../src/com/example/service/ProductService.java) — manages the in-memory product catalog.
- [`OrderService`](../src/com/example/service/OrderService.java) — creates orders and appends products.

## Project Structure

The source is organized into a few small packages under `src/com/example`:

- `src/com/example` — application entry classes.
- `src/com/example/controller` — thin coordination classes that call into services.
- `src/com/example/service` — in-memory business logic and state.
- `src/com/example/model` — domain objects such as users, products, and orders.
- `src/com/example/util` — shared helpers, mainly validation.

A useful mental model is: controllers receive calls, services make decisions, models carry data, and utilities provide reusable checks.

## Configuration

This repository does not appear to rely on a heavy framework or a large config surface. The main things to know are:

- `src/com/example/Application.java` wires together the user service and controller directly.
- `src/com/example/util/ValidationUtil.java` contains the email pattern and other shared validation rules.
- The services store data in local `Map` instances, so state is reset whenever a service is recreated.

If you add new behavior, check whether it belongs in code or whether a new config file is needed. At the moment, most behavior is hard-coded in the Java classes themselves.

## Common Patterns

A few patterns repeat throughout the codebase:

- **Thin controllers** — controllers mostly delegate instead of implementing business rules.
- **In-memory state** — services keep data in `Map` objects and assign ids locally.
- **Constructor wiring** — dependencies are passed into controllers through constructors.
- **Simple validation** — `ValidationUtil` returns booleans, while services decide whether to throw or accept input.
- **Mutable domain objects** — `User` and `Order` can be updated after creation, while `Product` is mostly read-only after construction.

## Suggested First Trace

If you only read one path through the code, follow this one:

`Application` -> `UserController` -> `UserService` -> `ValidationUtil` -> `User`

That sequence shows the project’s basic layering, validation style, and state flow without requiring any broader context.