Compliance Engine
Cloud-ready Java backend service validating structured records against configurable business rules with deterministic logic and LLM explanations.
The Challenge
Compliance rule validation is mission critical but complex. Organizations need systems that can evaluate records against business rules checking required fields, numeric thresholds, regex patterns, and allowed values all with full traceability and auditability.
The key requirement: rules must evaluate deterministically. No randomness, no ambiguity. And when a record fails, the system must explain exactly why in language stakeholders understand.
Your Role
API Design & Implementation
Built RESTful endpoints for managing rules, ingesting records, evaluating compliance, and persisting violations. Clean contract, proper HTTP semantics, comprehensive error handling.
Database Architecture
Designed PostgreSQL schema with appropriate constraints, indexes, and foreign keys. Modeled rules, records, and violations for scalable rule evaluation and compliance tracking.
Deterministic Evaluation
Implemented rule evaluation logic ensuring correctness and auditability. Every decision is traceable. Zero floating-point comparisons, no hidden state.
Deployment & Monitoring
Containerized with Docker, deployed to AWS using managed database and compute services. Set up monitoring, logging, and alerting for production reliability.
System Architecture
Three-tier architecture: REST API → Rule Evaluation Engine → PostgreSQL database. Each layer is independent and testable.
API Layer
REST Endpoints
- POST /rules (create rule)
- POST /evaluate (check record)
- GET /violations (audit trail)
- PUT /rules/:id (update)
Evaluation Engine
Rule Logic
- Required field checks
- Numeric comparisons
- Regex validation
- Allowed value constraints
Database
PostgreSQL
- Rules table
- Records table
- Violations table
- Audit log table
Key Technical Decisions
1. REST API Over Message Queue
Initial design considered async messaging (Kafka) for rule evaluation. We pivoted to synchronous REST for simplicity and immediate feedback.
- Why REST: Synchronous evaluation gives immediate pass/fail, essential for real-time validation
- Trade-off: Slightly higher latency than async, but accuracy and feedback matter more than throughput here
- Scale: Evaluated for ~100 req/sec baseline; messaging would add unnecessary complexity
2. PostgreSQL Over NoSQL
Rules and violations have strong relationships and need transactions. PostgreSQL enforces schema integrity; NoSQL would require application-level validation.
- ACID guarantees: Critical for compliance auditing
- Complex queries: JOINs across rules, records, and violations are natural in SQL
- Indexes: Built-in support for efficient rule lookups and violation searches
3. Docker Compose for Local Development
Every developer gets an identical environment: Java app + PostgreSQL in containers. No "it works on my machine" problems.
- Consistency: Dev, test, and production environments are all based on same Docker images
- Speed: New developers can spin up full stack in minutes
- Isolation: Database state is ephemeral; easy to reset
4. LLM Integration for Violation Explanations
Rule violations are deterministic, but explanations benefit from natural language. We integrated Claude API to generate human-readable violation descriptions.
- Trust: LLM explains violations; actual logic remains deterministic and auditable
- Flexibility: Same violation can be explained in multiple ways without changing evaluation logic
- Fallback: If LLM fails, system still returns structured violation data
Results
Required, numeric, regex, enum—extensible for more
Per record, fully traced and auditable
All rule types, edge cases, error paths
Production-ready reliability
What I Learned
1. Compliance Demands Clarity
Error messages matter. "Field validation failed" is useless. "Field 'age' must be between 18 and 120, got 200" is actionable. Spent as much time on error messaging as rule logic.
2. Auditability is Non-Negotiable
Every decision must be traceable. We log rule version, timestamp, user, inputs, and result. This isn't overhead—it's the entire point.
3. Determinism Over Cleverness
Temptation to add heuristics or ML-based compliance. Resisted. Simple, deterministic logic beats intelligent ambiguity in compliance contexts.
4. Test the Database Too
Application logic is tested; database queries are often assumed to work. Spent time writing integration tests for actual SQL. Caught several edge cases.
Let's talk
Interested in the technical approach, backend systems design, or compliance engineering? Let's connect.