# Repository Overview

Welcome to the **KOPT** repository — a Java-based module built under the `com.optage.kopt` package for the Optage platform. This project appears to be a scaffold for a batch-processing and service-orchestration system, with modules handling segregation-of-duties (SOD) workflows, contract processing, and external event triggering. If you're new here, this document is your starting point.

The codebase is currently in a fixture-driven scaffolding phase: classes are auto-generated for SPEC-SCOPED-WIKI tests, providing the structural bones (method signatures, package organization, cross-module wiring) while method bodies remain as stubs awaiting real business logic. As implementation matures, expect these placeholder methods to be filled in with production-grade code.

## Overview

This repository is a Java project organizing code under `com.optage.kopt`. Its purpose, based on the class names and structure, appears to be a service orchestration layer that coordinates several domains:

- **SOD (Segregation of Duties) operations** — validation, dispatch, and sending of SOD-related requests (in `bp` and `dto`).
- **Contract processing** — primary and secondary contract handling with external trigger integration (in `ekk` and `kkw`).
- **Batch processing** — sequential batch step fixtures (in `batch`).
- **ESC (Energy Supply Controller) subsystem** — a placeholder service controller (in `esc`).
- **Test fixtures** — isolated classes for dependency-detection tests (in `unrelated`).

The project has **65 graph nodes** and **58 graph edges** connecting the classes, indicating a moderately interconnected module graph even at this early stage.

## Technology Stack

No well-known frameworks (Spring, Micronaut, Quarkus, etc.) were detected from import analysis. The project uses:

- **Java** — the primary language
- **JUnit** — test infrastructure (evident from `JKKHakkoSODCCTest`)
- Auto-generated fixture classes for SPEC-SCOPED-WIKI tests

This suggests the project is currently at a very early stage or is designed as a lightweight, framework-free codebase where business logic is added without a heavyweight application container.

## Architecture

At a high level, the system is organized into six top-level packages under `com.optage.kopt`. The two packages with the most cross-module interactions are `bp` (which delegates to `batch` and uses `dto`) and `ekk` (which triggers events through `kkw`).

```mermaid
flowchart TD
    subgraph Modules["KOPT Modules"]
        BATCH["batch
KKPRC14901, KKPRC24901, KKPRC34901"]
        BP["bp
JKKHakkoSODCC, JKKSodSendCC, JKKHakkoSODHelper"]
        DTO["dto
JKKSodRequestDTO, JKKSodResponseDTO"]
        EKK["ekk
EKK0301A010, EKK0301A020"]
        ESC["esc
ESC0101B001"]
        KKW["kkw
KKW0100B001"]
        UNRELATED["unrelated
XYZ99999Unrelated"]
    end
    BP --> BATCH
    BP --> DTO
    EKK --> KKW
```

**Key relationships:**

- `bp` delegates validation to `batch` and exchanges data via `dto`.
- `ekk` pushes events to `kkw` via the `KKW0100B001` trigger mechanism.
- `esc` and `unrelated` are currently independent — no imports in or out.

## Module Guide

### `com.optage.kopt.batch`

This package provides three batch-processing step classes: `KKPRC14901` (primary), `KKPRC24901` (secondary), and `KKPRC34901` (tertiary). The naming convention encodes processing order (1xx through 3xx suffixes). `KKPRC14901` is the most implemented — its `run()` method delegates to `EKK0301A010` in the `ekk` package, making it the primary cross-module entry point. All three classes serve as fixtures for SPEC-SCOPED-WIKI tests.

### `com.optage.kopt.bp`

The `bp` package is the heart of the SOD (Segregation of Duties) workflow. Its central class, `JKKHakkoSODCC`, orchestrates the process through two phases: `validate()` (which delegates to `KKPRC14901.check()` in the batch package) and `dispatch()` (which hands off to `JKKSodSendCC` for the actual send operation). Supporting utilities include `JKKBpServiceBase` for shared initialization and `JKKHakkoSODHelper` for string formatting. This package ties together `batch` for validation and `dto` for data exchange.

### `com.optage.kopt.dto`

A lightweight package containing two plain Java objects: `JKKSodRequestDTO` (holding `tenantId` and `serviceId`) and `JKKSodResponseDTO` (holding `status` and `message`). These form a basic request/response envelope for the SOD pipeline. They are self-contained with no external dependencies and serve as the data contract between the `bp` package and downstream processing.

### `com.optage.kopt.ekk`

The contract processing layer with two classes: `EKK0301A010` (primary) and `EKK0301A020` (secondary). Both expose a `process()` method as their entry point. `EKK0301A010` also has a `notify()` method that creates a `KKW0100B001` instance and calls `trigger()`, wiring EKK contract events into the `kkw` subsystem. This is where the `batch -> ekk -> kkw` integration chain connects.

### `com.optage.kopt.esc`

A minimal package with a single fixture class, `ESC0101B001`, providing an empty `control()` method. It is currently isolated — no imports in or out — and appears to be a placeholder for a future ESC service control feature. No one calls into this package, and it does not call anything else.

### `com.optage.kopt.kkw`

This package contains `KKW0100B001`, a class whose `trigger()` method is intended to serve as a batch-trigger entry point. Currently an empty stub, it is consumed by `EKK0301A010.notify()`, making it the outbound edge of the EKK-to-KKW integration. Follow the `KKW` + numeric ID + version naming convention if extending this package.

### `com.optage.kopt.unrelated`

A deliberately isolated package containing `XYZ99999Unrelated`, a no-op class with no fields, no behavior, and no dependencies. It exists solely to help tests verify that cross-module dependency detection works correctly — it is an intentional "island" in the module graph.

## Getting Started

If you're new to this codebase, here is a recommended reading order to build mental models of the system:

1. **Start with `dto`** — Read `JKKSodRequestDTO` and `JKKSodResponseDTO`. These are the simplest classes and give you the data vocabulary the system uses.

2. **Explore `batch`** — Read `KKPRC14901` first, since it has the most implemented logic (`run()` delegates to `EKK0301A010`). Then skim `KKPRC24901` and `KKPRC34901` to understand the batch step convention.

3. **Move to `bp`** — Read `JKKHakkoSODCC` to understand the SOD workflow orchestration. Then read `JKKSodSendCC`, `JKKHakkoSODHelper`, and `JKKBpServiceBase` for supporting components. Follow the test class `JKKHakkoSODCCTest` for a usage example.

4. **Continue to `ekk`** — Read `EKK0301A010` to see how contract processing integrates with the `kkw` trigger mechanism via `notify()`. Then read `EKK0301A020`.

5. **Read `kkw`** — Finally, read `KKW0100B001` to complete the integration chain. This is the final destination of the `ekk.notify() -> kkw.trigger()` flow.

6. **Skim `esc` and `unrelated`** — These are stubs with no active wiring. Read them if you need to understand the full package layout or are working on dependency analysis tooling.

### Entry Points

The most important entry points to explore first:

| Class | File | Why |
|-------|------|-----|
| `JKKHakkoSODCC` | `bp/JKKHakkoSODCC.java` | Central SOD orchestrator — the main entry point for the SOD workflow |
| `KKPRC14901` | `batch/KKPRC14901.java` | Primary batch step with the most implementation |
| `EKK0301A010` | `ekk/EKK0301A010.java` | Primary contract processor and bridge to `kkw` |
| `JKKSodRequestDTO` | `dto/JKKSodRequestDTO.java` | The request data envelope — simplest class to understand |
| `JKKHakkoSODCCTest` | `bp/JKKHakkoSODCCTest.java` | Test class showing how `JKKHakkoSODCC` is exercised |

### Recommended Reading Order

```
dto/JKKSodRequestDTO -> batch/KKPRC14901 -> bp/JKKHakkoSODCC
  -> ekk/EKK0301A010 -> kkw/KKW0100B001
```

This path follows the primary data flow through the system, from request data through batch validation to contract processing and external triggering.