How department-of-veterans-affairs/abd-vro works
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 Gradle plugins · ee-ep-merge-app EE merge app · docker-compose.yml Compose stack · svc-bip-api BIP API
Components 21
Domain services
Business services for merge processing, classification, event ingestion, and external-system facades.
- EE merge app · Stateful merge orchestration service with API, job runner, merge machine, and job store.
domain-ee/ee-ep-merge-app - CC app · Lookup-table driven contention classification and mapping service.
domain-cc/cc-app - Max CFI app · Diagnostic code lookup and updater service for classification support.
domain-ee/ee-max-cfi-app - BIE Kafka svc · Consumes contention events from Kafka, transforms them, persists records, and publishes RabbitMQ messages.
svc-bie-kafka - BIP API · Java facade over claim, contention, lifecycle, and station-of-jurisdiction operations backed by RabbitMQ.
svc-bip-api - BGS API · Ruby facade for BGS interactions with consumers, healthchecks, and a client layer.
svc-bgs-api - VRO Streamlit · Internal Streamlit app with authentication and database-backed operational pages.
vro-streamlit - Claim tracker · 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 · Centralized Gradle conventions for Java, Python, Ruby, containers, linting, and publishing.
gradle-plugins - RabbitMQ connector · Reusable AMQP/Camel primitives for request/response and async messaging.
shared/lib-rabbitmq-connector - Hoppy · Python async consumer/publisher/client primitives for RabbitMQ workflows.
shared/lib-hoppy - Persistence model · Shared entities and repositories for claims, veterans, submissions, audits, and BIE events.
shared/persistence-model - BIE Kafka model · 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 · Local PostgreSQL container and bootstrap scripts for persistent service data.
postgres - RabbitMQ · Local broker container and definitions for internal request/response messaging.
rabbitmq - DB init · Versioned schema setup and migration scripts, including domain-cc migrations.
db-init - Compose stack · 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 · Stand-in for the BIP claims API with claims, contentions, and lifecycle endpoints.
mocks/mock-bip-claims-api - Mock BGS · Stand-in for BGS interactions used by local and CI test flows.
mocks/mock-bgs-api - Mock BIP CE · Stand-in for BIP evidence/content service interactions.
mocks/mock-bip-ce-api - Mock Slack · Stand-in for Slack notifications and message capture.
mocks/mock-slack
Connections 34
- 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.