# Repository Overview

Welcome to the **Futurity** codebase — the core customer infrastructure and business support system (BSS) developed by K-Opticom, a fiber-optic broadband provider in Japan, under the Fujitsu engineering umbrella. This repository contains a massive Java EE application spanning roughly 59,000 source files and a code graph of over 2 million nodes, all working together to manage subscriber lifecycle operations — from new account registration and service provisioning through billing, change requests, and customer support.

If you are a new engineer joining this project, this page is your starting point. Below you will find a high-level map of what the system does, how its pieces fit together, and where to look when you need to understand or change a specific part of the code. Take your time exploring — the codebase is large, but it follows a well-established, repeatable pattern.

---

## Overview

Futurity is an end-to-end telecommunications BSS platform. It handles the full subscriber lifecycle for K-Opticom's fiber-optic broadband service, including:

- **New customer enrollment** — account creation, equipment ordering, address registration, and initial service provisioning
- **Service changes** — plan modifications, equipment exchanges, service suspension/resumption, and termination
- **Billing and payment** — invoice generation, payment processing via integrated gateways (Paygent, etc.), and fee adjustments
- **Customer support** — inquiry handling, repair dispatch, and complaint management
- **Integration** — communication with external partners such as NTT东日本, NTT西日本, and various equipment vendors

The system is designed around a multi-tier Java EE architecture with an EJB-based business layer, JSF-driven web interfaces, and a configurable BPM (business process management) framework that drives the majority of its workflows. Business logic is organized into domain-specific service classes (prefixed with country/region codes like `AC`, `CK`, `CN`, `CC`, `CH`, `JK`, `JKK`, `JKU`, `FU`, `PC`, etc.), each covering a distinct business area.

---

## Technology Stack

This is a traditional Java EE application without an external modern web framework. The detected technology components are:

| Category | Technology |
|---|---|
| **Language** | Java (EE, approximately Java 7–11 era) |
| **Business Layer** | EJB 3.x (Stateless Session Beans) |
| **Web UI** | JavaServer Faces (JSF 2.x), with `.jsp` views and `.js` client scripts |
| **BPM Framework** | Custom Fujitsu BPM framework (`com.fujitsu.futurity.bp.x21`) |
| **Entity / Persistence** | JPA-style entity classes extending `CAANSchemaInfo` |
| **Web Containers** | GlassFish / Sun Application Server (`sun-web.xml`, `sun-ejb-jar.xml`) |
| **Configuration** | Java `.properties` files, XML rule definitions |
| **Build Artifacts** | EJB JARs, WAR archives, `.def` batch definitions |
| **Data Formats** | XML (rules, definitions), CSV, EDI-style flat files |

No well-known third-party frameworks (Spring, Hibernate, etc.) were detected from import analysis. The codebase relies primarily on Java EE platform APIs and Fujitsu's internal BPM framework.

---

## Architecture

The system follows a classic three-tier Java EE architecture:

```mermaid
flowchart TD
    subgraph Client["Client Tier"]
        WebA["WebA<br/>JSF UI"]
        WebB["WebB<br/>JSF UI"]
        WebF["WebF<br/>Web Front"]
        WebR["WebR<br/>Web Remote"]
        WebRest["WebRest<br/>REST API"]
    end

    subgraph Service["Service / EJB Tier"]
        koptBp["koptBp<br/>Business Process"]
        koptModel["koptModel<br/>Entity Layer"]
        koptCommon["koptCommon<br/>Common Utilities"]
    end

    subgraph Batch["Batch Processing"]
        koptBatch["koptBatch<br/>Batch Jobs"]
        futurityBatch["futurity-app/batch<br/>Batch Definitions"]
    end

    subgraph Rules["Rule Engine"]
        futurityRule["futurity-app/rule<br/>XML Rules"]
        serviceProp["service/prop<br/>Config & Definitions"]
    end

    subgraph Consumer["Data Consumer"]
        futurityConsumer["futurity-app/consumer<br/>NAS / Data"]
    end

    WebA --> koptBp
    WebB --> koptBp
    WebF --> koptBp
    WebR --> koptBp
    WebRest --> koptBp

    koptBp --> koptModel
    koptBp --> koptCommon

    koptModel --> koptCommon

    koptBatch --> koptModel
    koptBatch --> koptCommon
    futurityBatch --> koptBatch

    futurityRule --> koptBp
    serviceProp --> koptBp
    serviceProp --> koptModel

    futurityConsumer --> koptBp
```

**Tier descriptions:**

- **Client Tier (WebA, WebB, WebF, WebR, WebRest):** Web-based front ends built with JSF for administrative and customer-facing screens. WebRest provides REST API endpoints. WebB includes JSP views and a rich set of JavaScript client-side scripts for form validation and UI logic.
- **Service / EJB Tier (koptBp):** The heart of the system. Contains hundreds of BPM flow classes (`ACSV`, `CCSV`, `CHSV`, etc.) that define the business process logic for each operation type. Each flow is backed by an `IBPRunnable` implementation and uses Fujitsu's internal BPM framework for transaction management, database access, and request validation.
- **Entity Layer (koptModel):** JPA-style entity classes that model the database tables. Each entity extends `CAANSchemaInfo` and defines table/column mappings along with primary key metadata. Organized by business area (e.g., `cbm`, `cbs`, `check`).
- **Common Utilities (koptCommon):** Shared utilities used across all tiers — character encoding (EBCDIC/SJIS conversion), file I/O, FTP, email, encryption, date manipulation, string utilities, and constant definitions.
- **Batch Processing (koptBatch, futurity-app/batch):** Nightly and scheduled batch jobs that handle bulk operations such as billing, fee processing, and data synchronization. Defined via `.def` files and executed through batch EJBs.
- **Rule Engine (futurity-app/rule, service/prop):** XML-based business rules and property files that configure system behavior without code changes. Covers fee parameters, shipping definitions, relational checks, and client API request/response mappings.

---

## Module Guide

### koptBp — Business Process (com.fujitsu.futurity.bp.custom)

This module is the core business logic engine. It contains hundreds of BPM flow classes, each representing a distinct business operation. Flows are organized by prefix:

- **ACSV** — Service registration and enrollment processes (e.g., `ACSV0001` through `ACSV0039`). These handle new customer sign-ups, equipment orders, and initial provisioning.
- **CCSV** — Contract and plan change processes (`CCSV0001` through `CCSV0011`). Manages plan modifications, cancellations, and reactivations.
- **CHSV** — Change request and customer operation processes (`CHSV0001` through `CHSV0032`). Covers address changes, equipment exchanges, repair dispatches, and other mid-contract modifications.
- Each flow class (e.g., `ACSV0001Flow`) is paired with an operation class (e.g., `ACSV0001OPOperation`) that implements the step-level logic using `IBPRunnable`.

Flows follow a consistent template-generated structure:
1. Request validation via `reqchk`
2. Database lookup and data preparation via `DBConnectionInfo`
3. Step-by-step operation execution via `IOperation` and `OperationBroker`
4. Transaction commit and response assembly

### koptModel — Entity / Data Model

This module contains the persistent data layer. All entity classes live under `eo.ejb` and extend `CAANSchemaInfo`. Key sub-packages:

- **`eo.ejb.cbm.entity`** — CBM (Customer Business Management) entities like `CK0321ETMsg`, `CK0321LE`, `CK0321SQLEntity`, `CN0011ETMsg`, etc. Each set typically includes:
  - `*ETMsg` — Schema/message definition (extends `CAANSchemaInfo`, defines table/column mappings)
  - `*LE` — Logical entity (data container)
  - `*SQLEntity` — SQL-level entity with parameter access
- **`eo.ejb.cbs`** — CBS (Customer Business Service) related entities
- **`eo.ejb.check`** — Validation and correlation check logic, including `correlate`, `item`, `itemrelation`, and `state` sub-packages
- **`eo.ejb.common`** — Shared common code including `JCCModelCommon` (large shared model), `EventIDList`, cache utilities, encryption, and character conversion helpers
- **`eo.ejb.domain`** — Domain classes (`JSYejbC0000001Domain` through `JSYejbC0000074Domain`) that encapsulate business concepts above the raw entity layer

### koptCommon — Shared Utilities

A comprehensive utility library used across all modules. Key areas:

- **Constants** (`eo/common/constant`) — Large string constant files (`JACStrConst.java` ~455KB, `JFUStrConst.java` ~476KB, `JZM0171Constant.java` ~135KB) containing Japanese business terminology, error messages, and configuration constants
- **Utilities** (`eo/common/util`) — EBCDIC/SJIS encoding conversion, file compression, FTP client, email/fax sending, XML/CSV parsing, encryption, date formatting, and various business-specific helpers
- **Character Encoding** — `JBAbcdicConv`, `JBAsjisConv` — critical for legacy mainframe integration with EBCDIC-encoded data

### koptWebA / koptWebB — Web UI Modules

- **koptWebA** — Administrative web application with JSF pages, serving back-office operations
- **koptWebB** — Customer-facing web application with JSP views and a large JavaScript codebase (~180+ `.js` files) handling form validation, AJAX calls, and UI interactions. Script naming convention: `C` prefix for general (CHW), `K` for contract/K-opticom (CKW), `N` for new (CNW), `R` for change (CRW)

### koptBatch — Batch Processing

EJB-based batch job container. Processes nightly batch operations including billing calculation, fee processing, and data exports. Uses `META-INF` deployment descriptors and interacts with the entity layer.

### futurity-app — Configuration and External Interfaces

- **`rule/`** — XML business rule files (`RULE0049001.xml` through `RULE0093001.xml`) defining fee parameters, shipping definitions, relational check rules, and system configurations
- **`batch/`** — Batch definition files (`.def`) specifying job parameters and step configurations
- **`service/prop/`** — Property and XML configuration files for service behavior, including API request/response mappings (`clientApi*.setting`, `serverApi*.setting`), authority controls, and logging definitions
- **`consumer/nas/`** — Static content, data files, and templates for external consumers (affiliate data, htdocs pages)

---

## Getting Started

If you are new to this codebase, here is a recommended reading order to build understanding:

### 1. Understand the Entry Points

- **`koptWebB/WebContent/WEB-INF/web.xml`** — Web application deployment descriptor; identifies the entry servlets and JSF configuration
- **`koptWebB/WebContent/WEB-INF/faces-config.xml`** — JSF navigation rules and managed beans
- **`koptBatch/META-INF/sun-ejb-jar.xml`** — EJB deployment configuration

### 2. Learn the Common Foundation

- **`koptCommon/src/eo/common/constant/`** — Start with any of the large constant files to understand the business terminology used throughout the codebase
- **`koptCommon/src/eo/common/util/`** — Review `JCCcomFileSearchUtil.java`, `JCCcomEncryptionUtil.java` for shared utilities
- **`koptModel/src/eo/ejb/common/`** — Study `JCCModelCommon.java` (the largest shared model class at ~82KB) to understand cross-domain logic

### 3. Explore a Complete Business Flow

- Pick a single flow, e.g., **`com/fujitsu/futurity/bp/custom/bpm/acsv0001/ACSV0001Flow.java`** (temporary registration screen information acquisition)
- Read its paired operation class **`ACSV0001OPOperation.java`**
- Trace the entity classes it uses, e.g., from `koptModel/src/eo/ejb/cbm/entity/`
- Follow the XML rules from **`futurity-app/rule/`** that govern the flow's behavior

### 4. Understand the Data Model

- Start with **`koptModel/src/eo/ejb/cbm/entity/CK0321ETMsg.java`** — a clear example of an entity definition with table/column mappings
- Look at the domain classes in **`koptModel/src/eo/ejb/domain/`** to see how business concepts are encapsulated

### 5. Configuration and Rules

- Browse **`futurity-app/rule/`** to see how XML rules drive business logic without code changes
- Review **`futurity-app/service/prop/`** property files for system-wide configuration
- Examine **`koptBatch/def/`** for batch job definitions

### Key Patterns to Recognize

- **Template-generated flows**: All BPM flow classes are generated from a template (version 3.2.0.a) and follow an identical structure
- **Three-class entity pattern**: Each business entity typically has `*ETMsg` (schema), `*LE` (entity), and `*SQLEntity` (SQL access) classes
- **Prefixed naming**: Business areas use 2-3 letter prefixes (AC, CK, CN, CC, CH, JK, JKK, JKU, FU, PC, SC, TU, WC, ZM) that appear consistently across flows, entities, constants, and utilities
- **Stateless EJBs**: Business operations use `@Stateless` session beans for transaction management
- **Property-driven behavior**: Most system configuration lives in `.properties` and `.xml` files rather than hardcoded values

This codebase rewards familiarity with its patterns. Once you recognize the naming conventions and template structure, navigating to the relevant code for any given business operation becomes straightforward.