# Eo / Web

## Overview

`eo.web` is the top-level web tier of the Eo application, responsible for presenting the user interface and handling HTTP requests through JavaServer Faces (JSF). It serves as the bridge between browser-based user interactions and the server-side business processing layers of the application.

The package operates at the `subpackage` level in the module index. While the current snapshot contains no individually indexed source files at this level, it organizes the JSF view infrastructure through its child `webview` sub-package, which in turn contains leaf modules representing individual JSF page views.

This area of the codebase represents the presentation tier -- the "last mile" of the application where business data is rendered to users and user input is collected, validated, and dispatched to downstream logic.

## Sub-module Guide

### eo.web.webview

The `webview` sub-package is the primary (and currently only) child of `eo.web`. It implements the JSF view tier and is described in detail in [Eo / Web / Webview](webview.md).

**What it does:** `webview` hosts all JSF backing beans and action logic classes that power the application's user-facing pages. It follows a consistent two-class-per-view pattern:

- **Backing beans** (e.g., `ACA001SFBean`) hold view-scoped state and expose JavaBean properties bound to UI components via EL expressions.
- **Logic classes** (e.g., `ACA001SFLogic`) contain the `execute()` action handler invoked when a user submits a form or clicks a button.

**How it relates to the parent:** `eo.web` delegates all view-level responsibility to `webview`. There are no additional child packages at the `eo.web` level itself -- `webview` is the sole organized concern. If new web-level capabilities are added (e.g., REST controllers, servlet filters), they would likely appear as sibling sub-packages under `eo.web`.

The `webview` package is structured as a flat hierarchy of leaf modules (e.g., `ACA001SF`), each representing a single JSF view. The current index documents one representative module; the pattern suggests there may be more view modules following the same structure, even though they are not yet captured in the code index.

### Child module relationships

Since `webview` is currently the only child and it uses a flat leaf-package structure for individual views, the relationship is straightforward:

```
eo.web
  └── eo.web.webview       (JSF view tier)
        └── ACA001SF       (leaf: single JSF view)
              ├── ACA001SFBean
              └── ACA001SFLogic
```

Each leaf module under `webview` is self-contained and follows the same bean/logic split. There are no inter-leaf dependencies -- views communicate through JSF navigation rules defined in XML, not through direct Java references.

## Key Patterns and Architecture

### Two-class JSF view pattern

The foundational architectural pattern in `eo.web.webview` is the separation of view state from view behavior. Every JSF page gets two corresponding classes:

```
[JSF page JSP]  <-->  [Bean: state holder]  <-->  [Logic: action handler]
```

This maps cleanly to the JSF lifecycle:
- **Bean properties** survive across render phases and are bound to UI components via EL (e.g., `#{aca001sfBean.value}`).
- **Logic methods** handle side-effectful operations -- form submissions, business processing, navigation decisions.

### Stub / scaffold pattern

A significant observation about the `eo.web` module is that its documented example (`ACA001SF`) contains stub code: the `execute()` method is an empty no-op, and the bean exposes only a single trivial read-only property. The Javadoc comment "Futurity view logic" signals that this module was created as a structural placeholder.

This suggests the broader `eo.web` module may contain many such scaffolds -- the package was set up with the plumbing (JSF wiring, bean declarations, navigation rules) in place, with the expectation that business logic would be filled in over time. Developers encountering similar empty action methods throughout the package should look for "futurity" or "future" Javadoc comments as indicators of intended-but-not-yet-implemented features.

### XML-driven wiring

Rather than relying on annotation-based bean discovery, `eo.web` uses XML configuration for all wiring:

- `faces-config.xml` declares managed beans and their scopes.
- `WEBGAMEN_*.xml` files define navigation rules and page flows.
- `x33S_*.xml` files provide additional navigation context.
- `external-refs.xml` references beans and logic from outside the standard JSF flow (possibly by a routing or dispatch mechanism).

This declarative approach means the same bean and logic classes can be reused across different navigation contexts without modifying Java code. To add a view to a new workflow, you add XML entries rather than changing code.

### Request lifecycle

The request flow through any module in `eo.web.webview` follows the standard JSF lifecycle:

1. **JSF Page Render Phase** -- JSF resolves the bean from `faces-config.xml`, instantiates it, and binds its properties to UI components in the JSP via EL.
2. **User Action** -- The user submits a form or clicks a command button.
3. **JSF Invoke Application Phase** -- JSF calls the logic class's `execute()` method as specified in the component's `action` attribute.
4. **JSF Render Response Phase** -- The return value (or `void`) of `execute()` determines the navigation outcome.

## Dependencies and Integration

### Inbound dependencies

The `ACA001SF` leaf module -- representative of the broader `webview` package -- is referenced across six configuration and view files:

| File | Classes Referenced | Role |
|------|-------------------|------|
| `faces-config.xml` | `ACA001SFBean` | Managed bean registration |
| `WEBGAMEN_FULL_ACA001.xml` | `ACA001SFBean`, `ACA001SFLogic` | Navigation rules |
| `WEBGAMEN_ACA001010PJP.xml` | `ACA001SFBean`, `ACA001SFLogic` | Navigation rules |
| `x33S_ACA001.xml` | `ACA001SFBean`, `ACA001SFLogic` | Navigation rules |
| `FULL_ACA001010PJP.jsp` | `ACA001SFBean`, `ACA001SFLogic` | JSF view page |
| `external-refs.xml` | `ACA001SFLogic` | External wiring |

The same bean and logic classes appear in multiple XML contexts, confirming that the wiring is modular and the same components participate in different navigation scenarios.

### External dependencies

This module depends on:

- **JavaServer Faces (JSF)** -- the backing bean and logic class models are standard JSF artifacts.
- **JSP** -- the view layer is implemented as `.jsp` files with JSF tag libraries.
- **XML configuration** -- `faces-config.xml` and navigation rule files are declarative, XML-based dependencies.
- **JavaBeans** -- backing beans follow standard JavaBean conventions (getters/setters).

### Cross-module relationships

The current code index does not detect cross-module relationships for `eo.web`. Given the stub nature of the documented view module, this is not unexpected -- downstream business processing logic has not yet been wired to external modules. When `execute()` methods are implemented, we would expect to see calls into domain services or DAO layers.

## Architecture diagram

The following diagram shows the structure of `eo.web` and its primary sub-module:

```mermaid
flowchart TD
    subgraph eo_web["eo.web - Web Tier"]
        direction TB
        WEBVIEW["eo.web.webview<br/>JSF View Tier<br/>Backing beans & action logic"]
    end

    WEBVIEW --> ACA001SF["ACA001SF<br/>Single JSF view<br/>Bean + Logic split"]

    subgraph ACA001SF_group["ACA001SF - JSF View Component"]
        direction TB
        BEAN["ACA001SFBean<br/>Backing bean<br/>State holder"]
        LOGIC["ACA001SFLogic<br/>Action logic<br/>execute() handler"]
        JSP["FULL_ACA001010PJP.jsp<br/>JSF view page"]
    end

    ACA001SF --> ACA001SF_group
    BEAN -->|JSF EL binding| JSP
    LOGIC -->|action=| JSP

    subgraph config["XML Wiring"]
        direction LR
        FACES["faces-config.xml<br/>Managed bean registration"]
        NAV1["WEBGAMEN_*.xml<br/>Navigation rules"]
        NAV2["x33S_ACA001.xml<br/>Navigation rules"]
        EXT["external-refs.xml<br/>External wiring"]
    end

    FACES -->|declares| BEAN
    NAV1 -->|references| BEAN
    NAV1 -->|references| LOGIC
    NAV2 -->|references| BEAN
    NAV2 -->|references| LOGIC
    EXT -->|references| LOGIC

    subgraph request_flow["Request Lifecycle"]
        direction LR
        REQ["Browser request"]
        RENDER["JSF Render Phase<br/>Bean binds UI via EL"]
        ACTION["JSF Invoke Application<br/>Logic.execute()"]
        RESP["JSF Render Response<br/>Navigation outcome"]
        BROWSER["Browser response"]
    end

    REQ --> RENDER
    RENDER --> ACTION
    ACTION --> RESP
    RESP --> BROWSER
```

## Notes for Developers

- **Expect stub code.** The `ACA001SF` module demonstrates that the `eo.web` package contains no-op scaffolds. If you encounter classes with empty `execute()` methods throughout the package, this is expected behavior. Look for "futurity" or "future" Javadoc comments as indicators of planned-but-not-yet-implemented features.

- **Read-only bean properties.** `ACA001SFBean` exposes `value` only via a getter. If you create a new bean that needs form input binding (e.g., `<h:inputText value="#{bean.property}"/>`), remember to provide a corresponding setter -- the default pattern does not include one.

- **Entry point for new logic.** When extending a view module, the primary integration point is the `execute()` method on the logic class. This is where business processing, validation, and navigation decisions belong.

- **XML is the extension mechanism.** To add a view to a new workflow, you do not modify Java code -- you add entries to the appropriate `WEBGAMEN_*.xml` or `x33S_*.xml` navigation files and ensure the bean is registered in `faces-config.xml`.

- **No nested sub-packages.** `eo.web.webview` is a flat hierarchy. Each view module (e.g., `ACA001SF`) is a leaf package with no further nesting. New views should follow the same naming convention and bean/logic structure.

- **External wiring is possible.** The presence of `external-refs.xml` suggests that some views may be referenced outside the standard JSF flow, possibly by a custom routing or dispatch mechanism. Check this file if you suspect a view is being invoked from an unexpected source.

- **No downstream dependencies yet.** The current code index shows no cross-module relationships. When `execute()` methods are implemented, we would expect to see calls into domain services or DAO layers from the logic classes.