# Getting Started

Welcome to **KOPT** — a Java-based library built as part of the Optage platform. If you just joined the team, this guide will get you oriented in under ten minutes.

## What This Project Does

KOPT (`com.optage.kopt:optage-mini-fixture`) is a Maven-based Java library that provides scaffolding and fixture classes for the KOPT system. It covers batch processing entry points, Start-of-Day (SOD) processing coordination, contract processing, and service control. All classes in this repository are auto-generated test fixtures (marked `SPEC-SCOPED-WIKI`), meaning they serve as structural scaffolds for testing and documentation generation rather than production-ready business logic.

## Recommended Reading Order

Follow these steps to build your mental model of the codebase:

1. **[Overview](../overview.md)** — Start here for the full architecture diagram, module descriptions, and technology stack.
2. **[`pom.xml`](../../pom.xml)** — Confirms this is a Maven project with no external dependencies. It's 11 lines long.
3. **`KKPRC14901`** — The most complete batch entry point. Read it to see how schedulers invoke the system.
4. **`EKK0301A010`** — The contract processing class that `KKPRC14901` delegates to; shows the same lightweight pattern.
5. **`JKKHakkoSODCC`** — The SOD orchestrator; demonstrates the delegation pattern used across the codebase.
6. **`JKKSodSendCC`** — The dedicated SOD dispatch logic, showing how concerns are separated.
7. **`JKKSodRequestDTO` / `JKKSodResponseDTO`** — The shared data structures used by `bp` and `kkw`.
8. **`KKW0100B001`** — The leaf trigger class, completing the call chain from batch through contract processing to the downstream trigger.
9. **`JKKHakkoSODCCTest`** — Shows how tests are structured (JUnit 4).

## Key Entry Points

| Class | File | Role |
|---|---|---|
| `KKPRC14901` | [`batch/KKPRC14901.java`](../../src/main/java/com/optage/kopt/batch/KKPRC14901.java) | Primary batch entry point. Its `run()` method delegates to `EKK0301A010.process()`. Also provides a `check()` pre-flight validation hook. |
| `JKKHakkoSODCC` | [`bp/JKKHakkoSODCC.java`](../../src/main/java/com/optage/kopt/bp/JKKHakkoSODCC.java) | SOD orchestrator. `dispatch()` creates a `JKKSodSendCC` and calls `send()`; `validate()` delegates to `KKPRC14901.check()`. |
| `EKK0301A010` | [`ekk/EKK0301A010.java`](../../src/main/java/com/optage/kopt/ekk/EKK0301A010.java) | Contract processing entry point. `process()` is the main handler; `notify()` triggers the downstream `KKW0100B001.trigger()`. |
| `KKW0100B001` | [`kkw/KKW0100B001.java`](../../src/main/java/com/optage/kopt/kkw/KKW0100B001.java) | The leaf node in the dependency tree. Contains only a `trigger()` method and imports nothing. |

### How a call flows through the system

```mermaid
flowchart LR
    Sched["External Scheduler"] --> BP["JKKHakkoSODCC"]
    BP -->|dispatch| Send["JKKSodSendCC"]
    BP -->|validate| KKP["KKPRC14901"]
    KKP -->|runs| EKK["EKK0301A010"]
    EKK -->|notify| KKW["KKW0100B001"]
```

## Project Structure

The repository is a standard Maven project with a single Maven module.

```
pom.xml                              # Maven build descriptor
src/main/java/com/optage/kopt/       # Main source code
  batch/                             # Batch entry points
    KKPRC14901.java                  # Primary wired runner
    KKPRC24901.java                  # Stub scaffold
    KKPRC34901.java                  # Stub scaffold
  bp/                                # Start of Day processing
    JKKBpServiceBase.java            # Shared initialization base
    JKKHakkoSODCC.java               # SOD orchestrator (facade)
    JKKHakkoSODHelper.java           # Utility helper
    JKKSodSendCC.java                # SOD dispatch logic
    JKKHakkoSODCCTest.java           # JUnit 4 test (in bp, exercises SOD flow)
  dto/                               # Data transfer objects
    JKKSodRequestDTO.java            # Request: tenantId, serviceId
    JKKSodResponseDTO.java           # Response: status, message
  ekk/                               # Contract processing
    EKK0301A010.java                 # Contract processor
    EKK0301A020.java                 # Additional processor stub
  esc/                               # Service control
    ESC0101B001.java                 # Service control entry point
  kkw/                               # Batch trigger
    KKW0100B001.java                 # Downstream trigger (leaf node)
  unrelated/                         # Isolated test class
    XYZ99999Unrelated.java           # Completely standalone fixture
```

### Module overview

Each package under `com.optage.kopt` owns a specific functional domain:

- **`batch`** — Entry-point classes with `run()` methods, designed to be invoked by an external scheduler. `KKPRC14901` is the only wired runner; the other two are stubs.
- **`bp`** — Start-of-Day processing coordination. `JKKHakkoSODCC` acts as a facade delegating to `JKKSodSendCC` (dispatch) and `KKPRC14901` (validation).
- **`dto`** — Lightweight data carrier classes shared across modules. `JKKSodRequestDTO` and `JKKSodResponseDTO` form the core SOD data exchange.
- **`ekk`** — Contract processing. `EKK0301A010` is the primary processor; its `notify()` method reaches into the `kkw` package.
- **`esc`** — Standalone service control. No cross-module dependencies detected.
- **`kkw`** — Leaf trigger classes. `KKW0100B001` is the terminal node in the call chain.

```mermaid
flowchart TD
    subgraph KOPT["com.optage.kopt"]
        B["batch - Batch entry points"]
        BP["bp - SOD processing"]
        DTO["dto - Data objects"]
        EKK["ekk - Contract processing"]
        ESC["esc - Service control"]
        KKW["kkw - Batch trigger"]
    end
    B -->|invokes| EKK
    BP -->|dispatches| Send["JKKSodSendCC"]
    BP -->|validates via| KKP["KKPRC14901"]
    KKP -.->|also in| B
    EKK -->|notifies| KKW
    DTO -->|consumed by| BP
    DTO -->|consumed by| KKW
```

## Configuration

This project has no external dependencies and no application configuration files beyond Maven:

- **[`pom.xml`](../../pom.xml)** — Declares `com.optage.kopt:optage-mini-fixture:1.0.0-SPEC-SCOPED-WIKI` as a standalone JAR. No `<dependencies>` block, no plugins beyond the default Maven lifecycle. This is intentional: the repository exists as a structural fixture for testing and documentation.

## Common Patterns

Several conventions appear throughout the codebase:

1. **Delegation over monoliths.** Each class owns a single responsibility and delegates to others. For example, `JKKHakkoSODCC` does not implement dispatch logic itself — it creates a `JKKSodSendCC` instance and calls `send()`.

2. **Entry-point naming.** Batch entry points use the `KKPRC<spec><instance>` convention, contract processors use `EKK<spec><instance>`, SOD classes use `JKK<domain>CC` (Controller/Coordinator), and the leaf trigger uses `KKW<spec><instance>`.

3. **Single public method per class.** Most classes expose exactly one method (`run()`, `dispatch()`, `process()`, `trigger()`, etc.). This makes each class easy to understand in isolation.

4. **No constructors.** Classes use default (no-arg) constructors and instantiate collaborators inline (`new JKKSodSendCC().send()`). No dependency injection framework is used.

5. **Stub scaffolds.** Classes like `KKPRC24901`, `KKPRC34901`, `EKK0301A020`, and `XYZ99999Unrelated` have method bodies that are no-op comments. They exist to exercise the module structure and are safe to ignore when learning the core flow.

6. **Test placement.** Test classes live under `src/test/java` mirroring the source structure. The only test so far is `JKKHakkoSODCCTest`, which uses JUnit 4 `@Test` annotations.

## Next Steps

- Read the [full architecture overview](../overview.md) for dependency graphs and cross-module analysis.
- Explore the [batch](../com/optage/kopt/batch.md), [bp](../com/optage/kopt/bp.md), [ekk](../com/optage/kopt/ekk.md), and other module docs for package-level details.
- Run `mvn package` to verify the project builds (it should, since there are no dependencies to resolve).