# Eo

## Overview

The `eo` module is a top-level package within the application, most prominently featuring `eo.web` -- the presentation and web tier responsible for serving the user interface. This area represents the "last mile" of the application: it renders business data to users through JavaServer Faces (JSF) pages, collects and validates user input, and dispatches actions to downstream processing layers.

At the current snapshot, `eo` has no indexed source files or classes at the top level itself. Its observable structure flows entirely through its child package `eo.web`, which encapsulates the entire JSF-based UI infrastructure. The module appears to be in a scaffolded or early-development state -- example view modules contain no-op stubs with "futurity" Javadoc comments, suggesting the wiring and scaffolding are in place but business logic is yet to be filled in.

## Sub-module Guide

### eo.web -- Web / Presentation Tier

`eo.web` is the primary (and currently most concrete) child of `eo`. It contains the JSF view infrastructure, backing beans, and action logic that power the application's user-facing pages.

**What it does:** `eo.web` organizes all web-tier concerns under its `webview` sub-package, which hosts JSF backing beans and logic classes. It follows a consistent two-class-per-view pattern where each JSF page gets a backing bean (for view-scoped state) and a logic class (for the `execute()` action handler).

**Relationship to eo:** `eo.web` is the main observable concern under `eo`. If additional non-web sub-packages (e.g., `eo.api`, `eo.rest`) are added in the future, they would appear as siblings under `eo`.

See the full sub-module documentation at [Eo / Web](web.md) for detailed architecture and developer notes.

### Module hierarchy

```
eo
  └── eo.web                  (Web / Presentation Tier)
        └── 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.

## Key Patterns and Architecture

### Two-class JSF view pattern

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

| Class | Role |
|-------|------|
| **Backing bean** (e.g., `ACA001SFBean`) | Holds view-scoped state; exposes JavaBean properties bound to UI components via EL expressions |
| **Logic class** (e.g., `ACA001SFLogic`) | Contains the `execute()` action handler invoked on form submission or button click |

This maps cleanly to the JSF lifecycle:

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

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.

### Stub / scaffold pattern

A significant observation about the `eo` 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` 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:

| File | Role |
|------|------|
| `faces-config.xml` | Declares managed beans and their scopes |
| `WEBGAMEN_*.xml` | Navigation rules and page flows |
| `x33S_*.xml` | Additional navigation context |
| `external-refs.xml` | References beans and logic outside the standard JSF flow |

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.

### Flat leaf-package structure

`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.

## Dependencies and Integration

### Inbound dependencies

The representative `ACA001SF` leaf module 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`. 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`, how the sub-modules interact, and the request lifecycle through the JSF tier:

```mermaid
flowchart TD
    subgraph eo["eo - Application Module"]
        direction TB
        WEB["eo.web<br/>Web / Presentation Tier<br/>JSF UI layer"]
    end

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

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

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

    ACA001 --> ac001
    BEAN -->|"JSF EL binding"| JSP
    LOGIC -->|"action= bind"| JSP

    subgraph config["XML Wiring"]
        direction LR
        FACES["faces-config.xml<br/>Managed bean registration"]
        NAV1["WEBGAMEN_*.xml<br/>Navigation rules"]
        NAV2["x33S_*.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 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"]
        BROW["Browser response"]
    end

    REQ --> RENDER
    RENDER --> ACTION
    ACTION --> RESP
    RESP --> BROW
```

## Notes for Developers

- **Expect stub code.** The `ACA001SF` module demonstrates that the `eo` 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.

- **No indexed source files at `eo` top level.** The `eo` package itself contains no individually indexed source files at this snapshot. All observable structure flows through its children, primarily `eo.web`.