# Root

## Overview

This repository represents the top-level namespace for a **Japanese enterprise web application** built on Java EE / Jakarta EE technology. The root package itself contains no source files — it serves as the organizational umbrella under which three distinct architectural domains coexist:

- **`com`** — Application-specific business and integration code, subdivided into Fujitsu/Futurity web-facing code and Optage core banking processing.
- **`eo`** — The JSF-based presentation layer, providing server-side rendering and user-facing web pages.
- **`javax`** — The JavaServer Faces (JSF) framework namespace, providing the standard component-based web framework that the application depends on.

This is not a monolithic application but rather a **layered enterprise system** where each package under the root occupies a distinct tier: servlet infrastructure (startup, encoding, lifecycle), presentation (JSF views, beans, logic), business processing (SOD batch operations, contract handling), and the framework layer (JSF itself). The system appears to target Japanese domestic enterprise users, evidenced by Shift-JIS encoding support, Japanese character set references, and legacy XML-based configuration conventions.

## Sub-module Guide

The root namespace is divided into three sibling packages, each serving a different architectural role. Understanding how they interconnect is essential — the request flow through this system passes through all three in sequence.

### `com` — Application Business and Integration

The `com` package is the largest and most structurally diverse namespace. It is subdivided into three independent sub-domains:

| Sub-package | Role |
|---|---|
| `com.fujitsu` | Fujitsu-specific integration and the Futurity web application presentation entry point |
| `com.optage` | Core banking and financial processing (Start of Day operations) |
| `com.example` | Minimal stub classes for import resolution scaffolding |

These three sub-domains are **orthogonal** — they do not import from or depend on each other. `com.fujitsu` and `com.optage` are production-oriented packages with defined interfaces and architectural patterns, while `com.example` is a structural placeholder that ensures certain import declarations resolve at compile time.

### `eo` — JSF Presentation Layer

The `eo.web` module sits directly above the business logic in the architecture. It implements the **Page Controller pattern** adapted for JSF: each feature page has a managed bean (for view state) and a logic class (for action dispatch). Pages are wired through `faces-config.xml` and custom XML configuration files. Features are self-contained and do not coordinate with each other at runtime.

This is where user-facing JSP/JSF views connect to the application's business logic through the JSF managed bean and navigation framework.

### `javax` — JSF Framework Namespace

The `javax.faces` package provides the structural root of the JSF reference implementation. Its key sub-package, `javax.faces.webapp`, exposes the `FacesServlet` — the central dispatcher for all JSF HTTP requests. This is the bridge between the Servlet API (HTTP requests/responses) and the JSF framework (component trees, lifecycle phases, context objects).

`javax.faces` itself contains no local source files; its functionality is distributed across sibling sub-packages (`javax.faces.context`, `javax.faces.lifecycle`, `javax.faces.component`) that together implement the standard JSF specification.

### How the sub-modules relate

Together, these three packages form a **request processing pipeline** from HTTP entry to business logic to response rendering:

1. The **servlet layer** (within `com.fujitsu.futurity.web`) intercepts incoming HTTP requests from the container.
2. Requests pass through the `FacesServlet` (from `javax.faces.webapp`) which initializes the JSF lifecycle.
3. The **JSF view layer** (`eo.web`) renders pages using managed beans and logic classes.
4. Business logic delegates to **domain packages** (`com.optage.kopt` for banking, `com.fujitsu.futurity` for application-specific logic).
5. Responses flow back through the same layers to the servlet container.

The `com.example` package exists outside this flow — it is purely a compile-time scaffolding concern and has no runtime role.

```mermaid
flowchart TD
    subgraph SERVLET["com.fujitsu.futurity.web
(Servlet Layer)"]
        LISTENER["X33AppContextListener
Lifecycle management"]
        FILTER["X33JVRequestEncodingSjisFilter
Request encoding"]
    end

    subgraph JSF["javax.faces.webapp
(JSF Framework)"]
        FACES_SERVLET["FacesServlet
Request dispatcher"]
    end

    subgraph PRESENTATION["eo.web
(JSF Presentation)"]
        BEAN["Managed Bean
View state"]
        LOGIC["Logic Class
Action handling"]
        JSP["JSP/JSF Views
User interface"]
    end

    subgraph BUSINESS["com.optage.kopt
(Business Processing)"]
        BP["JKKHakkoSODCC
SOD orchestrator"]
        BATCH["KKPRC14901
Batch validation"]
        EKK["EKK0301A010
Contract processing"]
        KKW["KKW0100B001
Notifications"]
    end

    subgraph SCAFFOLD["com.example
(Import Scaffolding)"]
        KNOWN["KnownClass
Stub for imports"]
    end

    CONTAINER["Servlet Container
(Tomcat, WebSphere)"] -->|startup| LISTENER
    CONTAINER -->|HTTP request| FILTER
    FILTER -->|chain.doFilter| FACES_SERVLET
    FACES_SERVLET -->|JSF lifecycle| JSP
    JSP -->|reads state| BEAN
    JSP -->|dispatches action| LOGIC
    LOGIC -->|delegates| BP
    BP -->|validate| BATCH
    BATCH -->|process| EKK
    EKK -->|notify| KKW
    JSP -->|compile-time import| KNOWN

    style SERVLET fill:#e8d4f5
    style JSF fill:#c4e8c4
    style PRESENTATION fill:#c4d4f5
    style BUSINESS fill:#f5e8c4
    style SCAFFOLD fill:#f5c4c4
    style CONTAINER fill:#d4d4d4
```

## Key Patterns and Architecture

### Layered Enterprise Architecture

The system follows a **three-tier architecture** that is characteristic of Java EE applications from the mid-2000s era:

1. **Presentation tier** (`eo.web`, `javax.faces`) — Renders views and handles user interaction through JSF's component model and Page Controller pattern.
2. **Integration/servlet tier** (`com.fujitsu.futurity.web`) — Provides container-level lifecycle hooks and per-request processing through `ServletContextListener` and `Filter`.
3. **Business tier** (`com.optage.kopt`, `com.fujitsu.futurity`) — Encapsulates domain logic, batch processing, and external system integration.

### Servlet Lifecycle Archetype

The `com.fujitsu` package demonstrates a classic Java EE servlet pattern: a `ServletContextListener` for application-wide startup/shutdown and a `Filter` for per-request cross-cutting concerns (in this case, character encoding for Japanese content). This separation of concerns is architecturally sound — the lifecycle boundary handles one-time initialization, while the filter boundary handles per-request processing.

Both components are currently no-op stubs, which means the actual initialization and request processing is expected to occur through other mechanisms (Spring configuration, JSF managed beans, or downstream modules).

### JSF Page Controller Pattern

The `eo.web` module and the JSF framework (`javax.faces`) together implement a Page Controller pattern where:

- Each feature has its own managed bean (`*Bean`) and logic class (`*Logic`).
- Navigation is driven by `faces-config.xml` rules rather than return values.
- Beans are lightweight data conduits with minimal state.
- Logic classes handle user actions through a single `execute()` method.

This pattern enforces consistency across feature pages while keeping each feature self-contained.

### Delegation and Facade in Business Logic

The `com.optage.kopt` package uses a **facade pattern** at both the batch and business processing layers. `KKPRC14901` exposes a clean `check()`/`run()` interface that hides the complexity of contract processing (`EKK0301A010`), while `JKKHakkoSODCC` hides the multi-step workflow of validation, dispatch, and response assembly behind `validate()` and `dispatch()` methods.

Classes follow a **delegation over composition** pattern — creating new instance references for collaborators on each method call rather than holding long-lived injected dependencies. This keeps classes stateless but means instantiation overhead occurs on every invocation.

### Pre-flight / Execute Split

`KKPRC14901` implements a check-then-run pattern where validation and guard conditions are evaluated before the main batch logic. This two-phase approach is designed to catch errors early, though it is not yet consistently applied across all batch entry-points (`KKPRC24901` and `KKPRC34901` only provide `run()` at present).

### XML-Driven Wiring

Configuration throughout the system is **XML-centric** rather than annotation-driven:

- `web.xml` / `web-full.xml` registers servlets, filters, and listeners.
- `faces-config.xml` registers JSF managed beans and navigation rules.
- Custom XML files (`WEBGAMEN_FULL_ACA001.xml`, `x33S_ACA001.xml`, etc.) wire features across multiple deployment profiles.

A single feature can be referenced by five or more distinct configuration files, indicating broad activation across deployment profiles. This means any change to bean names, method signatures, or visibility modifiers requires coordinated updates across all affected XML configurations.

### Fixture-First Development

Several packages (`com.optage`, `com.example`, and portions of `com.fujitsu`) contain auto-generated fixture stubs rather than production logic. The architecture is designed top-down with class structures, method signatures, and inter-package dependencies established before implementation. This allows test infrastructure and documentation tooling to operate against a stable API surface.

### Dependency Flow

The system has a **strictly directional dependency chain** with no circular dependencies:

```
Servlet Container --> Servlet Layer --> FacesServlet --> JSF Views --> Business Logic
```

The `com.example` package breaks this chain — it has no inbound dependencies from the runtime flow and exists solely for compile-time import resolution.

## Dependencies and Integration

### Internal Dependencies

| Dependency | Relationship |
|---|---|
| `com.fujitsu.futurity.web` | Provides the servlet-level entry point for HTTP traffic |
| `com.fujitsu.futurity` | Contains lifecycle and filter stubs that bridge the container to application logic |
| `com.optage.kopt` | Handles core banking SOD operations; delegates through batch, contract, and notification layers |
| `eo.web` | Provides JSF-based presentation layer; reads state from beans, dispatches to logic classes |
| `javax.faces` | Provides the JSF framework infrastructure (FacesServlet, lifecycle, context) |
| `com.example` | Import resolution scaffolding with no runtime role |

### External Dependencies

| Dependency | Details |
|---|---|
| `javax.servlet.*` | Servlet API — used by the `com.fujitsu` filter, listener, and `FacesServlet` |
| `javax.faces.*` | JSF API — used by `eo.web` beans and logic classes |
| `web.xml` / `web-full.xml` | Deployment descriptors — register all servlet components and JSF configuration |
| Jakarta Faces (JSF) implementation | Mojarra or MyFaces provides the runtime JSF framework |
| Servlet containers | Tomcat, WebSphere, or equivalent — reads deployment descriptors and manages component lifecycle |
| Spring / JSF managed beans | Downstream business logic is expected to reside in Spring services or JSF backing beans not captured in the current index |

### Integration Summary

```mermaid
flowchart LR
    subgraph EXT["External"]
        CONTAINER["Servlet Container
Tomcat / WebSphere"]
        XML["web.xml
Deployment config"]
    end

    subgraph APP["Application"]
        SUB1["com.fujitsu
Servlet layer"]
        SUB2["javax.faces
JSF framework"]
        SUB3["eo.web
Presentation"]
        SUB4["com.optage
Business logic"]
        SUB5["com.example
Scaffolding"]
    end

    EXT -->|loads| XML
    XML -->|registers| SUB1
    XML -->|registers| SUB2
    SUB1 -->|routes| SUB2
    SUB2 -->|renders| SUB3
    SUB3 -->|delegates| SUB4
    SUB5 -.->|compile-time| SUB3
```

## Notes for Developers

### Current State: Partially Implemented

Several packages contain auto-generated fixture stubs or no-op implementations. Before adding new functionality:

- **`com.fujitsu.futurity`** — The `X33AppContextListener` and `X33JVRequestEncodingSjisFilter` are registered but perform no operations. Verify with downstream teams whether startup initialization or character encoding is expected at the servlet level.
- **`com.optage`** — All classes are auto-generated fixtures for SPEC-SCOPED-WIKI tests. Method bodies are no-op placeholders. The architecture is designed top-down; implement production logic against the established class structure and inter-package dependencies.
- **`com.example`** — The `KnownClass` stub exists solely for import resolution. If consuming JSPs have been refactored to remove their import references, this package and its parent may be safely deleted.

### Japanese Enterprise Context

This system appears to target Japanese domestic enterprise users:

- The filter `X33JVRequestEncodingSjisFilter` implies Shift-JIS (MS932) character encoding support.
- The `eo.web` module and JSF-based architecture are characteristic of enterprise applications serving Japanese-language content.
- The naming conventions (`JV` in filter name, numeric specification codes) follow Japanese enterprise development practices.

### Migration Considerations

The system uses `javax.servlet` and `javax.faces` namespaces. If the project migrates to Jakarta EE 9+:

- Package namespaces would need updating (`javax.servlet` to `jakarta.servlet`, `javax.faces` to `jakarta.faces`).
- The XML-based registration approach (`web.xml`, `faces-config.xml`) remains fully valid and portable.
- Consider migrating to annotation-driven registration (`@WebListener`, `@WebFilter`, `@WebServlet`) if reducing XML is a goal.

### Adding New Features

- **Web pages:** Follow the `eo.web` pattern — create a sub-package with a `*Bean` class and a `*Logic` class, then register both in `faces-config.xml` and relevant custom XML configs.
- **SOD batch operations:** Add new `KKPRC[N]4901` classes in `com.optage.kopt.batch` with `run()` methods delegating to the appropriate `EKK*` processors.
- **Servlet components:** Add listeners or filters under `com.fujitsu.futurity.web.x33` following the existing naming and registration conventions.

### Thread Safety

The servlet filter and listener in `com.fujitsu` currently hold no instance state, making them inherently thread-safe. Any future state added to these classes — particularly the filter, which handles every incoming request — must be carefully designed for thread safety. The `eo.web` bean classes should similarly avoid shared mutable state.

### XML Wiring Coordination

Before changing bean names, method signatures, or visibility modifiers in `eo.web`:

- Verify all XML configuration files that reference the changed elements.
- The `ACA001SF` feature, for example, is wired into at least five distinct XML configurations.
- A single change can cascade across multiple deployment profiles.

### Naming Conventions

Respect the existing naming patterns when adding new components:

- `KKPRC[N]4901` — Batch entry-point classes
- `JKK*[CC]` — Business processing classes
- `EKK0301A[0-9][0-9]` — Contract processors
- `KKW0100B[0-9][0-9]` — Notification classes
- `ESC0101B[0-9][0-9]` — ESC service classes

These patterns encode responsibility and should be maintained for consistency and discoverability.