AWS Builder Center

RuleFlow: Building an Explainable Policy Decision Engine on AWS

RuleFlow is a deterministic policy engine that makes eligibility decisions transparent and auditable. This article explains its rule evaluation, dependency graph, explainability, simulation capabilities, and AWS serverless architecture.

# Why Policy Decisions Need Explainability
Many real-world decisions are driven by rules: scholarship eligibility, compliance checks, benefits, admissions, and internal approvals. As these rules become more complex, it becomes difficult to understand exactly why a decision was made.
For the AWS First Commit hackathon, I built **RuleFlow**, an explainable policy and eligibility decision engine designed to make rule-based decisions deterministic, transparent, and auditable.
## What is RuleFlow?
RuleFlow allows organizations to define policies, evaluate cases against those policies, and understand the reasoning behind every decision.
A policy can contain rules such as:
- Age >= 18 - Annual income <= 250000 - CGPA >= 7.5 - Attendance >= 75 - Backlogs == 0
When a case is evaluated, RuleFlow produces an `ELIGIBLE` or `NOT_ELIGIBLE` decision along with detailed evidence for every rule.
Instead of only showing the final result, the system explains:
- Which rules passed - Which rules failed - The actual value received - The expected value - The operator used - A human-readable reason for the result
This makes the decision explainable rather than a black box.
## Deterministic Decision Engine
A key design principle of RuleFlow is that the actual decision is made by a deterministic rule engine.
The decision depends only on:
**Policy + Rules + Case Data + Evaluation Engine**
AI is not responsible for determining eligibility. Optional AI capabilities can be used to generate narrative explanations, while the deterministic engine remains the source of truth.
## Rule Dependency Graph
Rules can have dependencies on other rules, so RuleFlow represents policy logic as a directed graph.
The engine uses topological ordering to determine a deterministic execution sequence.
It also performs circular dependency detection.
For example:
`Rule A → Rule B → Rule C → Rule A`
is detected as an invalid policy instead of being allowed to create an unpredictable evaluation flow.
## Policy Simulation
RuleFlow includes a policy simulator that allows users to compare the current policy with proposed rule changes.
For example, an organization could change:
`CGPA >= 7.5`
to:
`CGPA >= 8.0`
and evaluate how that change affects existing cases.
This provides a way to understand the impact of policy changes before applying them.
## Audit Trail
Every important operation can be recorded through the audit system, including:
- Policy creation - Rule changes - Case evaluations - Policy simulations
This provides historical context for decisions and policy modifications.
## AWS Architecture
For the Ship It track, RuleFlow is designed around a serverless AWS architecture:
**React/Vite → AWS Amplify → Amazon API Gateway → AWS Lambda + FastAPI/Mangum → Amazon DynamoDB**
Amazon CloudWatch can be used for operational logging and monitoring.
The application uses configuration-driven AWS integration so deployment-specific values such as regions and DynamoDB table names are not hardcoded.
Amazon Bedrock can optionally provide natural-language explanation summaries. However, Bedrock does not make the underlying eligibility decision.
## What I Built
The platform includes:
1. Overview Dashboard 2. Policy Management 3. Visual Policy Builder 4. Case Evaluator 5. Decision Explanation 6. Dependency Graph 7. Policy Simulator 8. Audit History 9. System Telemetry
The Case Evaluator and Decision Explanation screens are particularly important because they show not only the final decision but also the evidence behind it.
## What I Learned
Building RuleFlow helped me understand how deterministic business logic, dependency graphs, explainability, and cloud infrastructure can work together.
The project also gave me practical experience designing a backend that can move from a local development environment toward a serverless AWS architecture.
## Conclusion
RuleFlow is built around a simple idea:
> **Don't just tell users what the decision is. Show them why.**
 By combining deterministic rule evaluation, dependency analysis, policy simulation, structured evidence, and auditability, RuleFlow provides a transparent foundation for policy-driven decisions. 

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article