# Eo

## Overview

The `eo` package is the top-level grouping for the application's web presentation layer. It is built on JavaServer Faces (JSF) and follows a classic Model-View-Controller (MVC) pattern across its sub-packages. Rather than containing standalone source files at its own level, `eo` organizes all web-facing functionality through child sub-modules — primarily `eo.web`, which in turn delegates to `eo.web.webview` and its view-specific packages.

At a high level, `eo` owns the entire rendering stack: it resolves backing beans from XML-registered scopes, renders JSP/JSF pages through EL expressions, and dispatches user actions to logic classes for processing. The package acts as the public face of the application, mediating between the user and the rest of the system.

The only current sub-module is `eo.web`, which encompasses the JSF-backed views. Within `web`, the `webview` sub-package is the workhorse — it houses named view modules (each identified by a code like `ACA001SF`), where each one represents a distinct page or feature area. Today, `ACA001SF` (the Futurity View) is the only indexed instance, but the structure is designed so that additional views can be added as independent namespaces under `eo.web.webview` without cross-talk.

## Sub-module Guide

The `eo` package has one immediate child: `eo.web`.

### eo.web

`eo.web` is the JSF-based presentation layer. It contains no source files at the package root itself — all its code lives in sub-packages under `eo.web.webview`. Each sub-package under `webview` is a self-contained unit comprising:

- A **backing bean** (JSF managed bean) that exposes properties via getters/setters.
- A **logic/action class** that processes form submissions and navigation decisions.
- **JSP/JSF view pages** that bind to the bean via EL expressions.

Currently, `webview` contains one sub-module:

**ACA001SF** — the Futurity View. It consists of `ACA001SFBean` (a JSF managed bean exposing a single read-only `String` property) and `ACA001SFLogic` (an action class with a no-op `execute()` method). Both are structural scaffolds — the implementation is intentionally minimal and serves as a template to be expanded as the Futurity feature matures.

### How the sub-modules relate

The hierarchy is strictly top-down: `eo` groups all web concerns; `eo.web` houses the JSF rendering logic; `eo.web.webview` contains individual view features; and each view sub-package (like `ACA001SF`) owns its bean, logic, config, and views. There is no lateral communication between sibling view modules — each sub-package under `webview` is an independent namespace. This means the system scales cleanly: adding a new page is a matter of creating a new sub-package under `webview` with the same bean-logic-view triad.

## Key Patterns and Architecture

### JSF MVC Triad

Every view sub-module under `eo.web.webview` adheres to the same three-part structure:

1. **Backling bean** — exposes properties via getters/setters for JSP EL binding. Properties are typically read-only (getter only), with initialization handled through `@PostConstruct` or DI injection.
2. **Logic/action class** — processes server-side actions. The `execute()` method is the primary extension point.
3. **JSP/JSF view pages** — render the UI and wire to the bean via EL expressions (e.g., `#{aca001sfBean.value}`).

This keeps presentation, data, and action logic cleanly separated within each sub-module's namespace.

### Request Flow

```mermaid
flowchart TD
    subgraph EO["Eo Package"]
        subgraph Web["eo.web"]
            subgraph Webview["eo.web.webview"]
                ACA001SF["ACA001SF Bean + Logic"]
            end
        end
    end

    subgraph Config["XML Configuration"]
        FC["faces-config.xml"]
        WF["WEBGAMEN configs"]
        X33S["x33S config"]
        ER["external-refs.xml"]
    end

    subgraph Views["JSP/JSF Views"]
        JSP1["JSP pages"]
    end

    subgraph Runtime["JSF Runtime"]
        BEAN["ACA001SFBean"]
        LOGIC["ACA001SFLogic"]
    end

    JSP1 --> BEAN
    JSP1 --> LOGIC
    BEAN --> LOGIC
    FC --> BEAN
    WF --> BEAN
    WF --> LOGIC
    X33S --> BEAN
    X33S --> LOGIC
    ER --> LOGIC
```

A typical request follows these steps:

1. The user navigates to a page (e.g., the Futurity JSP).
2. JSF resolves the backing bean (`ACA001SFBean`) from the XML-registered scope.
3. The JSP renders the view, binding to bean properties via EL expressions.
4. If the view triggers a server-side action (form submission, command link), the action is dispatched to the logic class (`ACA001SFLogic.execute()`).
5. The logic class processes the action, which may trigger state changes or navigation.

### Multiple Registration Paths

Components under `eo.web.webview` are registered across several XML configuration files (`faces-config.xml`, `WEBGAMEN_FULL_ACA001.xml`, `WEBGAMEN_ACA001010PJP.xml`, `x33S_ACA001.xml`, `external-refs.xml`). This appears intentional, allowing the same view components to operate under different scopes (request, view, session, application) or initialization parameters depending on which config profile is active for a given request. The presence of `WEBGAMEN` and `x33S` config profiles suggests integration with additional MVC frameworks or custom action-mapping layers alongside JSF.

### Dual Source Variants

Some logic classes (notably `ACA001SFLogic`) exist in dual source paths — a full-fixture source and an XML-unresolved-FQN source. Both share identical implementations but differ in Javadoc presence. This suggests a multi-branch or multi-profile build strategy. Changes to shared logic should be applied consistently across both paths to avoid divergence.

## Dependencies and Integration

### Inbound Dependencies

- **XML configurations** — `faces-config.xml` registers backing beans in JSF scopes, while `WEBGAMEN` and `x33S` config files register both beans and logic classes. `external-refs.xml` references the logic class, suggesting external service wiring.
- **JSP view pages** — View pages bind directly to backing beans and logic classes via EL expressions, driving the presentation layer.
- **Sibling configs** — The same bean and logic classes are referenced across all five XML configs, meaning the runtime behavior depends on which config profile is active.

### Outbound Dependencies

The current implementations are stubs and do not import or reference any external services, repositories, or application components. Any new services required as features expand should be wired through dependency injection or XML configuration.

The `eo` package sits at the top of the rendering stack — it is the entry point for all web requests and the final layer before the response is sent to the browser.

## Notes for Developers

- **Stub-level implementations.** The backing beans and logic classes are scaffolds. The `execute()` method on the logic class is the primary extension point — business logic should be added there as features grow.
- **Read-only bean properties.** Backing beans expose getters but not setters. If a view needs to accept user input, add a setter or populate the field via `@PostConstruct` initialization or DI injection.
- **Multiple configs, multiple lifecycles.** The same classes are registered in several XML files with potentially different scopes. Verify each config's scope and initialization parameters before relying on behavior — the bean may behave differently depending on which config profile is active.
- **Keep sub-modules self-contained.** The convention of one sub-package per view under `eo.web.webview` keeps beans, logic, configs, and JSPs co-located. Follow this pattern when adding new views.
- **Watch dual source paths.** Some classes exist in multiple source paths (full-fixture and XML-unresolved-FQN). If you modify a shared logic class, check whether a corresponding file exists in the other path and keep both in sync unless a clear canonical source has been designated.
- **The system is extensible.** The architecture is designed so that new view pages can be added simply by creating a new sub-package under `eo.web.webview` with the same bean-logic-view triad, without modifying existing modules.