# Eo

## Overview

The `eo` package represents the **top-level web presentation layer** of the Futurity application. It serves as the system's external-facing boundary — the entry point for all user-facing HTTP traffic — and organizes everything related to request routing, view rendering, and HTML response generation.

Architecturally, `eo` implements a server-side Model-View-Controller (MVC) pattern built on a Java EE platform (inferred to be Apache Struts 1.x) with JSP-based views. The package does not contain business logic itself; instead, it acts as the view and dispatch tier, accepting HTTP requests, routing them to the appropriate view logic classes, delegating to application services for data processing, and rendering HTML responses. This clean separation of concerns keeps the presentation layer lightweight and focused solely on user interaction.

The package is currently in a **skeleton or scaffold state**. A single sub-module (`ACA001SF`) exists as a structural template that demonstrates the intended MVC flow, but no active business logic has been wired up yet. This suggests `eo` is a foundational fixture awaiting feature implementation — a template that guides the creation of future web-facing modules.

## Sub-module Guide

The `eo` package delegates all presentation concerns to its one child module.

### eo.web

The `eo.web` package forms the **web presentation layer** — the actual HTTP-facing entry point for the system. It contains the MVC scaffolding, organized under the `webview` sub-package, which in turn contains feature modules that follow a shared structural pattern.

#### eo.web.webview.ACA001SF

The `ACA001SF` module is the sole implemented feature module and serves as the **reference pattern** for all future webview modules. It demonstrates the complete request lifecycle:

1. An XML action configuration (`WEBGAMEN_FULL_ACA001.xml`) maps an incoming HTTP request to a specific logic class.
2. The logic class (`ACA001SFLogic`) contains a stub `execute()` method — intended as the first place business logic will be added.
3. A data bean (`ACA001SFBean`) carries prepared data from the logic layer to the view layer.
4. JSP views read bean properties via Expression Language (EL) and render HTML.

#### How the modules relate

The relationship between `eo`, `eo.web`, and its sub-modules is hierarchical and layered:

```mermaid
flowchart TD
    Browser["Browser / HTTP Client"] -->|HTTP Request| Web["eo.web.webview"]
    Web -->|Routes via XML| Logic["*Logic classes<br/>(e.g. ACA001SFLogic)"]
    Logic -->|Populates| Bean["*Bean classes<br/>(e.g. ACA001SFBean)"]
    Bean -->|Request scope| JSP["JSP Views"]
    JSP -->|HTML Response| Browser
```

- **Independently extensible**: Each feature sub-module under `webview` encapsulates its own bean, logic, and views, so adding a new feature does not touch existing code.
- **Shared routing mechanism**: All modules are wired through the same XML-driven action configuration system, giving a single routing convention across the entire web layer.
- **Consistent naming**: The `ACA` prefix convention and `*Bean` / `*Logic` / JSP naming patterns ensure discoverability and reduce cognitive load when navigating between modules.

Future sub-modules (e.g., `ACA002SF`) should mirror this structure exactly, differing only in the specific data beans and business logic they implement.

## Key Patterns and Architecture

### Server-side MVC flow

The architecture follows a classic Struts 1.x MVC pattern. The expected flow for any request is:

1. An incoming HTTP request arrives at the application server.
2. The XML action configuration resolves the request path to a specific `*Logic` class.
3. `execute()` on the logic class processes the request — currently a stub, but intended to delegate to application services and populate data beans.
4. A `*Bean` is placed into request or session scope.
5. Control is forwarded to the JSP view, which reads the bean's properties and renders HTML.
6. The rendered HTML response is returned to the user's browser.

### JavaBeans as the data transport

Data flows between the logic and view layers through JavaBeans that follow the standard JavaBeans convention: private fields with public getters. This allows JSP EL and tag libraries to read properties without boilerplate.

Currently, beans are **read-only** — they define only getters, not setters. Data moves in one direction: from the logic layer into the view. If a future module needs to accept user input that binds back to a bean (e.g., form submission), a `setValue(String)` method must be added.

### XML-driven action mapping

Request routing is entirely **declarative**, controlled by XML configuration files rather than annotations or code. This has several implications:

- **Hot routing changes**: New action mappings can be added by editing XML without recompiling Java code (subject to framework hot-reload behavior).
- **Single source of truth**: The mapping files are the authoritative definition of route-to-logic associations.
- **Deployment sensitivity**: Changes to routing typically require a configuration reload or application restart.

### Dependency flow toward the business layer

The `eo` package has no internal business logic yet. The intended architecture delegates processing outward:

```mermaid
flowchart LR
    Browser["Browser"] -->|HTTP| Webview["eo.web.webview"]
    Webview -->|Routes via XML| Logic["*Logic classes"]
    Logic -->|Populates| Bean["*Bean classes"]
    Bean -->|Request scope| JSP["JSP views"]
    JSP -->|HTML| Browser
    Logic -.->|Future: delegates to| Services["Application services<br/>(business layer)"]
    Services -.->|Query| Data["Data layer<br/>(database, cache)"]
```

This unidirectional dependency flow ensures the web layer remains a pure presentation concern.

## Dependencies and Integration

### Internal dependencies

- **Application business layer** (inferred): While not yet connected, future `*Logic` classes are expected to delegate to service and domain packages for data access and business processing. The exact packages to depend on will be determined as features are implemented.

### External / framework dependencies

- **Struts framework** (inferred): The XML action configuration pattern and `*Logic` naming convention are characteristic of Struts 1.x. This is the primary request-dispatch framework.
- **JSP/Servlet API**: JSP views compile to servlets at runtime. All standard `javax.servlet` and `javax.servlet.jsp` APIs are available.
- **Java EE platform**: The module relies exclusively on Java EE platform APIs with no additional third-party library dependencies.

### Integration with the broader system

The `eo` package sits at the **top of the dependency tree**. It integrates with the rest of the application by:

1. **Accepting HTTP requests** from browsers or other HTTP clients.
2. **Delegating to application services** (future) for business processing and data access.
3. **Returning rendered HTML** to the client.

This places `eo` as the system's external-facing boundary — the single point where all user interaction enters the application.

## Notes for Developers

- **Skeleton stage**: The only implemented sub-module (`ACA001SF`) is a placeholder. Real logic has not yet been written into `execute()` methods. New feature development should start by implementing the logic class first, then wiring up the XML action config and JSP views.
- **Read-only beans**: Current beans define only getters, not setters. If a view needs to accept user input that binds back to a bean, a `setValue(String)` method must be added.
- **Naming conventions**: Sub-modules follow the `ACA` prefix convention. New modules should follow the same `*Bean` / `*Logic` / JSP naming pattern for consistency.
- **Extensibility model**: The package has no child sub-packages of its own — all extension happens by creating new sub-packages under `eo.web.webview` (e.g., a new feature area as `eo.web.webview.ACA002SF`).
- **No package-level dependencies**: The webview package has no outgoing dependencies beyond the Java EE platform. If new features require business logic, introduce dependencies on the appropriate service or domain packages.
- **Configuration management**: Action routing is managed through XML files (`WEBGAMEN_*.xml`). New sub-modules require corresponding entries in the action configuration XML.