# department-of-veterans-affairs/abd-vro architecture

> Architecture diagram of the GitHub repository department-of-veterans-affairs/abd-vro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/department-of-veterans-affairs/abd-vro
- Repository: https://github.com/department-of-veterans-affairs/abd-vro

## Overview

1. **Repository shape**
   - This is a multi-project monorepo for ABD VRO, not a single application.
   - It contains several domain-specific services, shared libraries, local infrastructure containers, and mock external systems.
   - The implementation spans **Python**, **Java/Spring Boot**, and **Ruby**, with **Gradle** used as the top-level build/cohesion layer.

2. **Primary business domains**
   - The repo is organized around VA claims automation workflows:
     - **EE**: end-to-end merge processing and claim lifecycle operations.
     - **CC**: claim/contention classification and lookup-driven mapping.
     - **BIE events**: ingestion and tracking of contention events.
     - **BIP/BGS adapters**: façades over external benefit/claim systems.
   - These domains are separated into independent services rather than one shared monolith.

3. **Core orchestration service: `domain-ee/ee-ep-merge-app`**
   - This is the most workflow-heavy service.
   - It has an API layer, a persistence layer, and a service layer centered on an `ep_merge_machine`, `job_runner`, and `job_store`.
   - It appears to coordinate claim merge operations, resume/restart behavior, and interactions with claim/contention APIs.
   - This service owns the state machine for merge jobs and persists job state in a database.

4. **Claims classification service: `domain-cc/cc-app` and `domain-ee/ee-max-cfi-app`**
   - `domain-cc/cc-app` is lookup-table driven: its source includes CSV/JSON datasets for dropdown lookups, diagnostic code mappings, and classification IDs.
   - `ee-max-cfi-app` is a lighter classification-style service built around a diagnostic code lookup table and updater script.
   - Both are data-driven services whose main architectural boundary is “classification logic + curated lookup data.”

5. **Event ingestion and bridging: `svc-bie-kafka`**
   - This service sits at the boundary between **Kafka** and **RabbitMQ**.
   - The code shows a `ContentionEventsListener`, record transformers, and an AMQP sender/service.
   - Architectural role: consume BIE contention events from Kafka, transform them into service-ready payloads, store/retrieve related records, and publish downstream messages over RabbitMQ.

6. **External-system façade services: `svc-bip-api` and `svc-bgs-api`**
   - `svc-bip-api` is a Java service that exposes claim/contention/lifecycle operations through an internal API and RabbitMQ-backed request handling.
   - It contains domain models for claims, contentions, special issue types, lifecycle updates, and temp station-of-jurisdiction changes.
   - `svc-bgs-api` is a Ruby service with a similar role for BGS interactions, including consumers, healthchecks, and a client layer.
   - These are adapter services: they shield the rest of the system from external API specifics.

7. **Shared asynchronous/messaging infrastructure**
   - The repo uses **RabbitMQ** as a central integration bus for request/response-style interactions and service-to-service messaging.
   - Shared support lives in `shared/lib-rabbitmq-connector` and `shared/lib-hoppy`, which provide reusable AMQP/Camel and async client/consumer primitives.
   - Kafka is present specifically for BIE event ingestion, while RabbitMQ is used more broadly for synchronous-style internal workflows and integration contracts.

8. **Persistence and database layer**
   - `shared/persistence-model` contains reusable JPA-style entities and repositories for claims, veterans, submissions, evidence documents, audits, and contention events.
   - `db-init` owns versioned DB migrations and initial schema setup, including a separate `domain-cc` migration path.
   - `postgres` is the local database container/bootstrap layer, showing that PostgreSQL is a core runtime dependency for services that persist workflow state and operational data.

9. **User-facing application: `vro-streamlit`**
   - This is the only obvious interactive front-end in the repo.
   - It is a Streamlit application with authentication, directory-style content pages, and a database-backed service layer.
   - It looks more like an internal operational/dashboard tool than a customer-facing product UI.

10. **Mock services and test harness**
    - `mocks/` contains stand-ins for external dependencies: BIP claims API, BGS API, Slack, Kafka/schema registry, and shared JWT/REST helpers.
    - The services include recorded fixtures, local keystores/truststores, and controller/model implementations that mimic external contracts.
    - This indicates the system is designed to run end-to-end locally or in CI without real external dependencies.

11. **Infrastructure and local deployment**
    - `docker-compose.yml`, service-specific compose files, and container Dockerfiles provide a full local stack.
    - `rabbitmq/`, `postgres/`, and `db-init/` are the core infrastructure containers.
    - The repo also includes Kubernetes-related assets under `.github/runner`, plus a `RunningKubernetesLocal.md`, suggesting deployment parity between local and platform environments.

12. **Build, CI/CD, and governance**
    - The root contains extensive GitHub Actions workflows for CI, container health checks, image publishing, end-to-end tests, and secret deployment.
    - The `gradle-plugins/` project centralizes build conventions for Java, Python, containers, linting, and publishing.
    - This repo is built to support many independently deployable services with consistent standards.

13. **Likely end-to-end data flow**
    - Events enter from Kafka or external APIs, are transformed by adapter services, and are published over RabbitMQ or persisted in PostgreSQL.
    - Workflow services like `ee-ep-merge-app` consume those APIs/messages, update job state, and drive claim merge actions.
    - Front-end and reporting tools like `vro-streamlit` read from persistence and present operational views.
    - Mock services replace real upstream/downstream systems in tests and local runs.

14. **Important architectural boundary to capture in a diagram**
    - The repo is best drawn as a set of **domain services** around a shared **messaging + persistence platform**.
    - Cross-cutting shared code is intentionally separated into libraries.
    - External dependencies are abstracted behind dedicated façade/mock services rather than being called directly from every application.

Main entry points: [`gradle-plugins`](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/gradle-plugins) (Gradle plugins), [`domain-ee/ee-ep-merge-app`](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/domain-ee/ee-ep-merge-app) (EE merge app), [`docker-compose.yml`](https://github.com/department-of-veterans-affairs/abd-vro/blob/develop/docker-compose.yml) (Compose stack), [`svc-bip-api`](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/svc-bip-api) (BIP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["ABD VRO"]
end

subgraph group_domain["Domain services"]
  node_ee_merge["EE merge app<br/>workflow service"]
  node_cc_app["CC app<br/>classification service"]
  node_ee_max_cfi["Max CFI app<br/>lookup service"]
  node_bie_kafka["BIE Kafka svc<br/>event bridge"]
  node_bip_api["BIP API<br/>adapter service"]
  node_bgs_api["BGS API<br/>adapter service"]
  node_streamlit["VRO Streamlit<br/>ops UI"]
  node_claim_tracker["Claim tracker<br/>python service"]
end

subgraph group_shared["Shared platform"]
  node_gradle_plugins["Gradle plugins<br/>build conventions"]
  node_shared_rabbitmq["RabbitMQ connector<br/>messaging lib"]
  node_shared_hoppy["Hoppy<br/>python mq lib"]
  node_shared_persistence[("Persistence model<br/>data model lib")]
  node_shared_bie_kafka["BIE Kafka model<br/>event schema lib"]
end

subgraph group_infra["Local runtime"]
  node_postgres[("Postgres<br/>db runtime")]
  node_rabbitmq["RabbitMQ<br/>broker runtime"]
  node_db_init["DB init<br/>migrations"]
  node_docker_compose["Compose stack<br/>local orchestration<br/>[docker-compose.yml]"]
end

subgraph group_mocks["Mock systems"]
  node_mock_claims["Mock claims<br/>mock service"]
  node_mock_bgs["Mock BGS<br/>mock service"]
  node_mock_bipce["Mock BIP CE<br/>mock service"]
  node_mock_slack["Mock Slack<br/>mock service"]
end

node_gradle_plugins -->|"builds"| node_ee_merge
node_gradle_plugins -->|"builds"| node_cc_app
node_gradle_plugins -->|"builds"| node_ee_max_cfi
node_gradle_plugins -->|"builds"| node_bie_kafka
node_gradle_plugins -->|"builds"| node_bip_api
node_gradle_plugins -->|"builds"| node_bgs_api
node_gradle_plugins -->|"builds"| node_claim_tracker
node_shared_rabbitmq -->|"messaging"| node_ee_merge
node_shared_rabbitmq -->|"messaging"| node_bip_api
node_shared_hoppy -->|"messaging"| node_claim_tracker
node_shared_hoppy -->|"messaging"| node_ee_merge
node_shared_persistence -->|"persistence"| node_ee_merge
node_shared_persistence -->|"persistence"| node_bie_kafka
node_shared_persistence -->|"data access"| node_streamlit
node_shared_bie_kafka -->|"event schema"| node_bie_kafka
node_db_init -->|"initializes"| node_postgres
node_docker_compose -->|"orchestrates"| node_postgres
node_docker_compose -->|"orchestrates"| node_rabbitmq
node_docker_compose -->|"orchestrates"| node_mock_claims
node_docker_compose -->|"orchestrates"| node_mock_bgs
node_docker_compose -->|"orchestrates"| node_mock_bipce
node_docker_compose -->|"orchestrates"| node_mock_slack
node_bie_kafka -->|"publishes"| node_rabbitmq
node_bie_kafka -->|"stores"| node_postgres
node_ee_merge -->|"calls"| node_bip_api
node_ee_merge -->|"consumes"| node_rabbitmq
node_ee_merge -->|"stores"| node_postgres
node_cc_app -->|"looks up"| node_bip_api
node_ee_max_cfi -->|"looks up"| node_bip_api
node_bip_api -->|"mimics"| node_mock_claims
node_bgs_api -->|"mimics"| node_mock_bgs
node_streamlit -->|"reads"| node_postgres
node_claim_tracker -->|"stores"| node_postgres
node_claim_tracker -->|"integrates"| node_rabbitmq

click node_gradle_plugins "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/gradle-plugins"
click node_shared_rabbitmq "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/shared/lib-rabbitmq-connector"
click node_shared_hoppy "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/shared/lib-hoppy"
click node_shared_persistence "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/shared/persistence-model"
click node_shared_bie_kafka "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/shared/lib-bie-kafka"
click node_ee_merge "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/domain-ee/ee-ep-merge-app"
click node_cc_app "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/domain-cc/cc-app"
click node_ee_max_cfi "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/domain-ee/ee-max-cfi-app"
click node_bie_kafka "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/svc-bie-kafka"
click node_bip_api "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/svc-bip-api"
click node_bgs_api "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/svc-bgs-api"
click node_streamlit "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/vro-streamlit"
click node_claim_tracker "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/domain-bie-events/svc-claim-tracker"
click node_postgres "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/postgres"
click node_rabbitmq "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/rabbitmq"
click node_db_init "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/db-init"
click node_docker_compose "https://github.com/department-of-veterans-affairs/abd-vro/blob/develop/docker-compose.yml"
click node_mock_claims "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/mocks/mock-bip-claims-api"
click node_mock_bgs "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/mocks/mock-bgs-api"
click node_mock_bipce "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/mocks/mock-bip-ce-api"
click node_mock_slack "https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/mocks/mock-slack"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ee_merge,node_cc_app,node_ee_max_cfi,node_bie_kafka,node_bip_api,node_bgs_api,node_streamlit,node_claim_tracker toneAmber
class node_gradle_plugins,node_shared_rabbitmq,node_shared_hoppy,node_shared_persistence,node_shared_bie_kafka toneMint
class node_postgres,node_rabbitmq,node_db_init,node_docker_compose toneRose
class node_mock_claims,node_mock_bgs,node_mock_bipce,node_mock_slack toneIndigo
```

## Components

### Domain services

Business services for merge processing, classification, event ingestion, and external-system facades.

- [EE merge app](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/domain-ee/ee-ep-merge-app): workflow service · Stateful merge orchestration service with API, job runner, merge machine, and job store. · `domain-ee/ee-ep-merge-app`
- [CC app](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/domain-cc/cc-app): classification service · Lookup-table driven contention classification and mapping service. · `domain-cc/cc-app`
- [Max CFI app](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/domain-ee/ee-max-cfi-app): lookup service · Diagnostic code lookup and updater service for classification support. · `domain-ee/ee-max-cfi-app`
- [BIE Kafka svc](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/svc-bie-kafka): event bridge · Consumes contention events from Kafka, transforms them, persists records, and publishes RabbitMQ messages. · `svc-bie-kafka`
- [BIP API](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/svc-bip-api): adapter service · Java facade over claim, contention, lifecycle, and station-of-jurisdiction operations backed by RabbitMQ. · `svc-bip-api`
- [BGS API](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/svc-bgs-api): adapter service · Ruby facade for BGS interactions with consumers, healthchecks, and a client layer. · `svc-bgs-api`
- [VRO Streamlit](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/vro-streamlit): ops UI · Internal Streamlit app with authentication and database-backed operational pages. · `vro-streamlit`
- [Claim tracker](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/domain-bie-events/svc-claim-tracker): python service · BIE-event claim tracking service with API and PostgreSQL persistence. · `domain-bie-events/svc-claim-tracker`

### Shared platform

Reusable messaging, persistence, and build conventions used across services.

- [Gradle plugins](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/gradle-plugins): build conventions · Centralized Gradle conventions for Java, Python, Ruby, containers, linting, and publishing. · `gradle-plugins`
- [RabbitMQ connector](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/shared/lib-rabbitmq-connector): messaging lib · Reusable AMQP/Camel primitives for request/response and async messaging. · `shared/lib-rabbitmq-connector`
- [Hoppy](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/shared/lib-hoppy): python mq lib · Python async consumer/publisher/client primitives for RabbitMQ workflows. · `shared/lib-hoppy`
- [Persistence model](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/shared/persistence-model): data model lib · Shared entities and repositories for claims, veterans, submissions, audits, and BIE events. · `shared/persistence-model`
- [BIE Kafka model](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/shared/lib-bie-kafka): event schema lib · Shared Java models and annotations for BIE contention event payloads. · `shared/lib-bie-kafka`

### Local runtime

Database, broker, and startup layers for local and CI execution.

- [Postgres](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/postgres): db runtime · Local PostgreSQL container and bootstrap scripts for persistent service data. · `postgres`
- [RabbitMQ](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/rabbitmq): broker runtime · Local broker container and definitions for internal request/response messaging. · `rabbitmq`
- [DB init](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/db-init): migrations · Versioned schema setup and migration scripts, including domain-cc migrations. · `db-init`
- [Compose stack](https://github.com/department-of-veterans-affairs/abd-vro/blob/develop/docker-compose.yml): local orchestration · Top-level compose definitions and service wiring for running the repo locally. · `docker-compose.yml`

### Mock systems

Stand-ins for external integrations used in local development and tests.

- [Mock claims](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/mocks/mock-bip-claims-api): mock service · Stand-in for the BIP claims API with claims, contentions, and lifecycle endpoints. · `mocks/mock-bip-claims-api`
- [Mock BGS](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/mocks/mock-bgs-api): mock service · Stand-in for BGS interactions used by local and CI test flows. · `mocks/mock-bgs-api`
- [Mock BIP CE](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/mocks/mock-bip-ce-api): mock service · Stand-in for BIP evidence/content service interactions. · `mocks/mock-bip-ce-api`
- [Mock Slack](https://github.com/department-of-veterans-affairs/abd-vro/tree/develop/mocks/mock-slack): mock service · Stand-in for Slack notifications and message capture. · `mocks/mock-slack`

## Connections

- Gradle plugins → EE merge app: builds · Applies shared build conventions to the merge service.
- Gradle plugins → CC app: builds · Applies shared build conventions to the classification service.
- Gradle plugins → Max CFI app: builds · Applies shared build conventions to the lookup service.
- Gradle plugins → BIE Kafka svc: builds · Applies shared build conventions to the Kafka bridge.
- Gradle plugins → BIP API: builds · Applies shared build conventions to the BIP adapter.
- Gradle plugins → BGS API: builds · Applies shared build conventions to the Ruby BGS adapter.
- Gradle plugins → Claim tracker: builds · Applies shared build conventions to the claim tracker service.
- RabbitMQ connector → EE merge app: messaging · Provides AMQP and Camel primitives for workflow integration.
- RabbitMQ connector → BIP API: messaging · Provides RabbitMQ request/response plumbing.
- Hoppy → Claim tracker: messaging · Provides Python async queue/client primitives.
- Hoppy → EE merge app: messaging · Supports async queue interactions in the merge workflow.
- Persistence model → EE merge app: persistence · Shares claim and merge-related entities/repositories.
- Persistence model → BIE Kafka svc: persistence · Shares BIE event persistence models and repositories.
- Persistence model → VRO Streamlit: data access · Provides operational read models for the UI service.
- BIE Kafka model → BIE Kafka svc: event schema · Defines common contention event payload types.
- DB init → Postgres: initializes · Loads versioned schema and migration scripts into Postgres.
- Compose stack → Postgres: orchestrates · Starts the database container as part of the local stack.
- Compose stack → RabbitMQ: orchestrates · Starts the broker container as part of the local stack.
- Compose stack → Mock claims: orchestrates · Includes mock claim API in local integration stacks.
- Compose stack → Mock BGS: orchestrates · Includes mock BGS in local integration stacks.
- Compose stack → Mock BIP CE: orchestrates · Includes mock BIP CE in local integration stacks.
- Compose stack → Mock Slack: orchestrates · Includes mock Slack in local integration stacks.
- BIE Kafka svc → RabbitMQ: publishes · Transforms Kafka ingests into downstream AMQP messages.
- BIE Kafka svc → Postgres: stores · Persists and retrieves contention event records.
- EE merge app → BIP API: calls · Uses claim and contention APIs to drive merge steps.
- EE merge app → RabbitMQ: consumes · Uses queue-based workflow and service interactions.
- EE merge app → Postgres: stores · Persists merge job state and restart metadata.
- CC app → BIP API: looks up · Uses claim/contention context for classification mapping.
- Max CFI app → BIP API: looks up · Serves diagnostic code classification support.
- BIP API → Mock claims: mimics · Local and CI tests validate BIP contract behavior against the mock.
- BGS API → Mock BGS: mimics · Local and CI tests validate BGS contract behavior against the mock.
- VRO Streamlit → Postgres: reads · Uses database-backed service data for operational pages.
- Claim tracker → Postgres: stores · Persists tracked claim records and related state.
- Claim tracker → RabbitMQ: integrates · Participates in messaging-based service workflows.
