> For the complete documentation index, see [llms.txt](https://host2host.onibonje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://host2host.onibonje.com/docs/11-repository-structure.md).
# Repository Structure
## 1. Overview
The platform is organized as a **Maven multi-module monorepo**. Each module is an independently versioned JAR published to the internal artifact repository and composed into the runtime deployable.
## 2. Directory Layout
```
heirs-h2h-platform/
├── pom.xml # Parent POM
├── README.md
├── docs/ # Architecture documentation
│
├── h2h-bom/
│ └── pom.xml # Bill of Materials
│
├── h2h-common/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/common/
│ ├── model/ # Canonical message models
│ ├── error/ # Error codes and exceptions
│ ├── trace/ # Correlation ID utilities
│ └── util/ # Shared utilities
│
├── h2h-config-api/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/config/api/
│ ├── ConfigResolver.java # Interface
│ ├── dto/ # IntegrationProfile, TransformSpec, etc.
│ └── event/ # ConfigPublishedEvent
│
├── h2h-config-store/
│ ├── pom.xml
│ └── src/main/
│ ├── java/com/heirs/h2h/config/store/
│ │ ├── entity/ # JPA entities
│ │ ├── repository/ # Spring Data repositories
│ │ └── migration/ # Flyway config
│ └── resources/db/migration/
│ ├── V1__create_partner_tables.sql
│ ├── V2__create_route_template_tables.sql
│ ├── V3__create_transform_tables.sql
│ ├── V4__create_validation_tables.sql
│ └── V5__create_config_version_audit.sql
│
├── h2h-config-runtime/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/config/runtime/
│ ├── DefaultConfigResolver.java
│ ├── ConfigCache.java
│ ├── ConfigVersionService.java
│ ├── ConfigValidator.java
│ └── ConfigEventListener.java
│
├── h2h-camel-core/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/camel/
│ ├── core/
│ │ ├── CorrelationIdProcessor.java
│ │ ├── ConfigResolverProcessor.java
│ │ ├── IdempotencyProcessor.java
│ │ ├── AuditProcessor.java
│ │ ├── StepExecutor.java
│ │ ├── StepRegistry.java
│ │ └── GlobalErrorHandler.java
│ ├── component/
│ │ └── IdempotentComponent.java
│ └── config/
│ └── CamelCoreAutoConfiguration.java
│
├── h2h-security/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/security/
│ ├── vault/ # Vault client wrapper
│ ├── pgp/ # PGP encrypt/decrypt
│ ├── camel/ # crypto: component
│ └── config/
│ └── SecurityAutoConfiguration.java
│
├── h2h-camel-core/
│
├── h2h-core-banking-api/ # CBS BASE LIBRARY — vendor-neutral
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/corebanking/api/
│ ├── CoreBankingIntegration.java
│ ├── CoreBankingProviderRegistry.java
│ └── CoreBankingOperationProvider.java
│
├── h2h-finacle-wrapper/ # CBS provider type: FINACLE
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/finacle/
│ ├── adapter/
│ ├── internal/
│ ├── camel/
│ └── config/
│
├── h2h-cbs-mock/ # CBS provider type: MOCK
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/cbs/mock/
│
├── h2h-file-adapter/ # Legacy SFTP adapter (superseded by file-management)
│
├── h2h-file-management/ # Unified file system: SFTP, S3, signed URLs
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/filemgmt/
│ ├── api/ # FileManagementService
│ ├── store/ # FileStore SPI (Sftp, S3, Azure, GCS)
│ ├── signed/ # SignedUrlService
│ ├── delivery/ # FileDeliveryManager
│ ├── registry/ # FileRegistryRepository
│ └── camel/ # file-mgmt: component
│
├── h2h-context/ # Execution context framework
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/context/
│ ├── H2hContext.java
│ ├── H2hContextBuilder.java
│ ├── H2hContextHolder.java
│ └── ContextPropagator.java
│
├── h2h-observability/ # Monitoring and logging library
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/observability/
│ ├── logging/ # StructuredLogEncoder, MDC
│ ├── metrics/ # H2hMetrics, MetricsRecorder
│ ├── tracing/ # OtelTraceManager
│ ├── audit/ # AuditEventPublisher
│ └── health/ # Custom health indicators
│
├── h2h-mq-adapter/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/mq/
│ ├── kafka/
│ └── config/
│ └── MqAdapterAutoConfiguration.java
│
├── h2h-http-ingress/ # REST/SOAP sync HTTP entry
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/http/
│ ├── dynamic/ # DynamicHttpEndpoint from channel_config
│ └── config/
│
├── h2h-websocket-ingress/ # WebSocket real-time push
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/websocket/
│ ├── session/ # Partner session registry
│ ├── push/ # EventWebSocketDispatcher
│ └── config/
│
├── h2h-transform-core/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/transform/
│ ├── engine/ # JOLT, JSONata, XSLT engines
│ ├── camel/ # transform: component
│ └── config/
│ └── TransformAutoConfiguration.java
│
├── h2h-transform-iso20022/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/transform/iso20022/
│
├── h2h-transform-mt940/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/transform/mt940/
│
├── h2h-ack-nack/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/acknack/
│
├── h2h-payments-routes/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/payments/
│ ├── route/ # Camel RouteBuilder classes
│ └── config/
│ └── PaymentsRoutesAutoConfiguration.java
│
├── h2h-collections-routes/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/collections/
│
├── h2h-statements-routes/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/statements/
│
├── h2h-reconciliation/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/reconciliation/
│
├── h2h-admin-api/
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/admin/
│ ├── controller/ # REST controllers
│ ├── service/ # Business logic
│ └── config/
│ └── AdminApiAutoConfiguration.java
│
├── h2h-extension-api/ # SPI interfaces for plugins
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/extension/
│ ├── spi/ # ExtensionProvider, Customizer, HookExecutor
│ ├── model/ # CustomizationProfile, extension blocks
│ └── api/ # ExtensionRegistry, CustomizationResolver
│
├── h2h-extension-kernel/ # Central extension registry and resolver
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/extension/kernel/
│ ├── DefaultExtensionRegistry.java
│ ├── DefaultCustomizationResolver.java
│ ├── CustomizationCache.java
│ ├── ExtensionValidator.java
│ └── HookExecutorImpl.java
│
├── h2h-script-engine/ # Sandboxed script execution
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/script/
│ ├── engine/ # Groovy, GraalVM, JSONata
│ ├── sandbox/ # Security sandbox
│ └── processor/ # ScriptExecuteProcessor
│
├── h2h-job-scheduler/ # Broker-delayed jobs (Kafka / RabbitMQ)
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/job/
│ ├── scheduler/ # ScheduleBootstrap, DelayedJobPublisher, DelayedJobRelay
│ ├── executor/ # Script, SQL, Camel, HTTP executors
│ └── config/
│ └── JobSchedulerAutoConfiguration.java
│
├── h2h-workflow-api/ # Maker–checker contracts
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/workflow/api/
│ ├── ApprovalService.java
│ ├── ApprovalPolicyResolver.java
│ └── dto/
│
├── h2h-workflow-camunda/ # Camunda multi-level approval engine
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/workflow/camunda/
│ ├── CamundaApprovalService.java
│ ├── MakerCheckerDelegate.java
│ ├── camel/ # camunda: component
│ └── config/
│ └── WorkflowAutoConfiguration.java
│
├── h2h-persistence-spi/ # Database-agnostic persistence
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/persistence/
│ ├── spi/ # JsonColumnMapper, SqlTaskExecutor
│ └── dialect/ # PostgreSQL, Oracle, SQL Server
│
├── h2h-webhook-dispatcher/ # Event → webhook delivery
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/webhook/
│
├── h2h-notification-api/ # Notification SPI
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/notification/api/
│
├── h2h-notification-dispatcher/ # Event → email/SMS/push
│ ├── pom.xml
│ └── src/main/java/com/heirs/h2h/notification/dispatcher/
│
├── h2h-notification-aws-ses/ # EMAIL provider
├── h2h-notification-sendgrid/
├── h2h-notification-smtp/
├── h2h-notification-twilio/ # SMS provider
├── h2h-notification-africas-talking/
├── h2h-notification-termii/
├── h2h-notification-slack/
│
├── h2h-runtime/
│ ├── pom.xml # Profiles: boot-jar | war | docker
│ ├── Dockerfile # Profile A only (optional)
│ └── src/main/
│ ├── java/com/heirs/h2h/runtime/
│ │ ├── H2hRuntimeApplication.java
│ │ └── H2hRuntimeWarInitializer.java # Profile C — WAR
│ └── resources/
│ ├── application.yml
│ └── application-{env}.yml
│
├── h2h-admin-ui/ # Next.js admin portal
│ ├── package.json
│ ├── src/
│ │ ├── app/ # Next.js app router pages
│ │ ├── components/ # UI components
│ │ └── lib/ # API client, utilities
│ └── Dockerfile
│
├── h2h-partner-portal/ # Next.js partner portal
│ ├── package.json
│ └── src/
│
├── helm/
│ └── h2h-platform/
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│
├── docker/
│ └── docker-compose.yml # Local dev environment
│
└── .github/
└── workflows/
├── build.yml # CI: build, test, publish JARs
├── docker.yml # CI: build and push images
└── archunit.yml # CI: architecture rule checks
```
## 3. Parent POM
```xml
4.0.0
com.heirs.h2h
heirs-h2h-platform
1.0.0-SNAPSHOT
pom
Heirs H2H Integration Platform
h2h-bom
h2h-common
h2h-config-api
h2h-config-store
h2h-config-runtime
h2h-camel-core
h2h-core-banking-api
h2h-security
h2h-finacle-wrapper
h2h-file-adapter
h2h-file-management
h2h-context
h2h-observability
h2h-mq-adapter
h2h-http-ingress
h2h-websocket-ingress
h2h-transform-core
h2h-transform-iso20022
h2h-transform-mt940
h2h-ack-nack
h2h-payments-routes
h2h-collections-routes
h2h-statements-routes
h2h-reconciliation
h2h-admin-api
h2h-extension-api
h2h-extension-kernel
h2h-script-engine
h2h-job-scheduler
h2h-persistence-spi
h2h-webhook-dispatcher
h2h-event-extensions
h2h-runtime
21
3.3.0
4.6.0
UTF-8
com.heirs.h2h
h2h-bom
${project.version}
pom
import
```
## 4. Module Dependency Graph
```
h2h-runtime
├── h2h-camel-core
│ ├── h2h-config-runtime
│ │ ├── h2h-config-store
│ │ │ └── h2h-config-api
│ │ │ └── h2h-common
│ │ └── h2h-config-api
│ └── h2h-common
├── h2h-config-runtime
├── h2h-security
│ └── h2h-common
├── h2h-finacle-wrapper
│ ├── h2h-core-banking-api
│ │ └── h2h-common
│ └── h2h-common
├── h2h-core-banking-api
│ └── h2h-common
├── h2h-file-adapter
│ ├── h2h-security
│ └── h2h-config-api
├── h2h-mq-adapter
│ └── h2h-common
├── h2h-payments-routes
│ ├── h2h-camel-core
│ ├── h2h-core-banking-api # interface only — not finacle-wrapper internals
│ ├── h2h-file-adapter
│ ├── h2h-transform-core
│ └── h2h-ack-nack
├── h2h-admin-api
│ ├── h2h-config-store
│ └── h2h-config-runtime
├── h2h-file-management
│ ├── h2h-security
│ ├── h2h-context
│ └── h2h-config-api
├── h2h-context
│ └── h2h-config-api
├── h2h-observability
│ ├── h2h-context
│ └── h2h-security
├── h2h-extension-kernel
│ ├── h2h-extension-api
│ └── h2h-config-runtime
├── h2h-script-engine
│ ├── h2h-extension-api
│ ├── h2h-extension-kernel
│ ├── h2h-config-api
│ └── h2h-context
├── h2h-job-scheduler
│ ├── h2h-script-engine
│ ├── h2h-persistence-spi
│ └── h2h-camel-core
├── h2h-persistence-spi
│ └── h2h-common
└── (optional route modules)
```
## 5. Naming Conventions
| Element | Convention | Example |
| ------------------- | ----------------------------------------------------------- | --------------------------------------------- |
| Group ID | `com.heirs.h2h` | — |
| Module artifact | `h2h-{capability}` | `h2h-finacle-wrapper` |
| Java package | `com.heirs.h2h.{capability}` | `com.heirs.h2h.finacle` |
| Route ID | `{domain}-{action}` | `bulk-payment-split` |
| Step code | `SCREAMING_SNAKE` | `PGP_DECRYPT` |
| Config table | `snake_case` | `integration_profile` |
| Kafka topic / queue | Logical `event_code` → `event_channel_def.destination_name` | `PAYMENT_POSTED` → `heirs.ng.payments.posted` |
| Vault path | `{type}/{scope}/{entity}/{key}` | `secret/pgp/acme/public-key` |
| Docker image | `heirs-h2h/{module}:{version}` | `heirs-h2h/runtime:1.4.0` |
## 6. Build Commands
```bash
# Build all modules
mvn clean install
# Build and publish to Artifactory
mvn clean deploy
# Build runtime Docker image
cd h2h-runtime && docker build -t heirs-h2h/runtime:latest .
# Run locally with docker-compose
docker-compose up -d # PostgreSQL, Kafka, Vault, Mock Finacle
# Run runtime locally
cd h2h-runtime && mvn spring-boot:run -Dspring-boot.run.profiles=local
# Run ArchUnit checks
mvn test -pl h2h-camel-core -Dtest=ArchitectureTest
```
## 7. CI/CD Pipeline
```yaml
# .github/workflows/build.yml (simplified)
name: Build and Test
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
java-version: '21'
distribution: 'temurin'
cache: maven
- run: mvn clean verify
- run: mvn deploy -DskipTests
if: github.ref == 'refs/heads/main'
```
## 8. Local Development Environment
`docker-compose.yml` provides:
| Service | Port | Purpose |
| ---------------- | ---- | -------------------- |
| PostgreSQL | 5432 | Config store |
| Kafka (KRaft) | 9092 | Event backbone |
| Vault (dev mode) | 8200 | Secrets |
| Mock Finacle | 8081 | Finacle sandbox mock |
| SFTP (atmoz) | 2222 | SFTP testing |
| Redis | 6379 | Idempotency cache |
## 9. Related Documents
* [Modular JAR Architecture](/docs/03-modular-jar-architecture.md)
* [Technology Stack](/docs/02-technology-stack.md)
* [Implementation Roadmap](/docs/10-implementation-roadmap.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://host2host.onibonje.com/docs/11-repository-structure.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.