Configurable gateway for regulatory safety reporting
We designed a reporting platform that maps enterprise source data to standard objects and then to each regulator's message format. A nine-step wizard handles configuration, and secrets are mounted read-only, replacing two hard-coded legacy reporting services.
Direct answer. We replaced two hard-coded reporting services with one gateway that maps enterprise data to standard objects, then to each regulator’s message format, through configuration rather than code, with signing, delivery, receipts, retries and audit built in.
Summary
Industrial enterprises in a regulated safety sector must report work permits, personnel, real-time positions and risk-control data to government platforms. Each platform has its own fields, signing, encryption and receipt rules. Implementation staff configure a new integration in a nine-step wizard, and secrets are mounted read-only on the host.
Problem
Each new enterprise, enterprise-system version or regulator-platform version used to mean code changes in legacy services. Business meaning was spread across scripts and special cases. Integration work depended on developers and was hard to audit.
Constraints
- Legacy code could be used to find business special cases, but not to shape the new architecture.
- Implementation staff must not edit SQL, YAML, JSON or scripts. The design target: at least 95% of new integrations configured through the UI, the rest through a stable plugin interface. This target still has to be proven with real samples.
- Deployment on customer premises, including offline sites, with a pinned image architecture and verifiable image IDs.
- Credentials never stored in configuration. Only logical references are stored.
Architecture
| Part | Implementation |
|---|---|
| Backend | Java 21, Spring Boot 4.1, MySQL 8, Flyway migrations V1 to V14 |
| Console | Vue 3 + TypeScript configuration UI |
| Mapping | Two stages: source fields to a standard object, then the standard object to the target message, expressed as a closed expression tree rather than a scripting language |
| Wizard | Nine steps: scope, data source, probe, standard mapping, target message, platform capability, test, approval, release |
| Delivery runtime | Authentication, signing and encryption; HTTP, TCP and messaging transports; sync and async receipts; scheduling, increments, idempotency, retry, re-reporting and reconciliation |
| Secrets | Read-only, file-based secret store mounted into the container |
Key decisions
- Closed mapping language. A bounded expression tree can be validated and audited before release, which free-form scripts cannot, so a reviewer can see exactly what a mapping will send.
- Standard objects in the middle. Because sources and targets meet only at the standard object, adding a new enterprise system or a new regulator version touches one side of the mapping.
- Safe operations by default. Smoke tests check health only, and real sending needs an explicit flag. Rollback refuses to downgrade the image once the database is on a newer migration and points the operator to the pre-upgrade backup instead.
Evidence
- 78 backend test classes. 14 versioned migrations. Four business domains in the first scope: work permits, personnel, real-time positioning and dual-prevention risk control.
- Requirements baseline, audit report, decision log, staged acceptance checklist and deployment manual are part of the delivery.
Limits
The 95% configurability target is a design goal and has not been validated in the field. Regulator names, endpoints and enterprise data are not published.
Frequently asked questions
Can non-developers add a new enterprise integration?
That is the design target. Implementation staff work through the nine-step wizard. Capabilities outside the product's scope go through a plugin interface, not changes to the core.
How are credentials protected?
Configuration stores only a logical credential reference. Real secrets are read from a read-only mounted directory on the host.
Does it run offline?
Images can be built on a connected machine, exported, then loaded and checked by image ID on site.