# Eo / Web

## Overview

The `eo.web` package represents the **web presentation layer** of the Futurity application. It serves as the entry point for all user-facing HTTP traffic, handling request routing, view rendering, and response generation. This layer implements a server-side MVC (Model-View-Controller) architecture built on a Java EE framework (inferred to be Apache Struts 1.x) with JSP-based views.

At the architectural level, `eo.web` does not contain business logic. 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 separation of concerns ensures the web layer remains lightweight and focused on presentation.

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

## Sub-module Guide

The `eo.web` package delegates all presentation concerns to its `webview` sub-package, which in turn contains feature sub-modules that follow a shared structural pattern.

### eo.web.webview

The `webview` sub-package forms the core of the web presentation tier. It contains the MVC scaffolding — action configuration files, view logic classes, data beans, and JSP templates — organized by feature area.

#### ACA001SF

The `ACA001SF` module is the sole implemented sub-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`) currently contains an empty `execute()` method — intended to be the first place business logic is added.
3. A data bean (`ACA001SFBean`) carries prepared data to the view layer.
4. JSP views read bean properties and render HTML.

#### How sub-modules relate

All webview sub-modules are expected to follow the same **bean-logic-JSP** triad:

- **Independently extensible**: Each sub-module 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 (Struts-style), giving a single routing convention across the entire web layer.
- **Consistent naming**: The `ACA` prefix pattern and `*Bean` / `*Logic` / JSP naming conventions 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, where the web layer drives the entire request lifecycle:

```mermaid
flowchart TD
    User["User / Browser"] -->|HTTP Request| XMLConf["XML Action Config<br/>(WEBGAMEN_*.xml)"]
    XMLConf --> Logic["View Logic<br/>(*Logic.execute())"]
    Logic -->|Populates| Bean["Data Bean<br/>(*Bean)"]
    Bean -->|Request scope| JSP["JSP Views"]
    JSP -->|HTML Response| User
```

The expected flow for any request:

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 via EL (Expression Language) 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. This means 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 to the bean.

### 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, making them useful for understanding the application's URL structure.
- **Deployment sensitivity**: Changes to routing typically require a configuration reload or application restart.

### Dependency flow toward the business layer

The `eo.web.webview` 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.web` package sits at the **top of the dependency tree** — it has no outgoing dependencies beyond the framework and Java EE platform. 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.web` as the system's external-facing boundary.

## 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 to the bean.
- **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.