HLD: Design a system that levies penalties or taxes on riders/drivers based on constraints like completing a minimum number of rides per month or getting below-average ratings.
If you’re looking for paid 1:1 mentorship with a strong focus on LLD (core emphasis on Multithreading), HLD, DSA, and system design research papers, feel free to reach out.
📩 Contact: programmingappliedai@gmail.com
Functional Requirements (FR)
Penalty/Tax Rule Management
System should allow admins to define and manage dynamic rules for penalties/taxes based on:Minimum rides completed
Cancellation rate
Average rider/driver ratings
Inactive days
Peak-hour participation
Fraud signals
Periodic Evaluation Engine
System should periodically evaluate riders/drivers (daily/weekly/monthly) against configured rules and determine applicable penalties or taxes.Penalty Calculation & Ledger Management
System should calculate penalty amounts accurately and maintain a financial ledger/history for every deduction, adjustment, refund, or waiver.Notification & Transparency
Users should receive notifications explaining:Why the penalty was applied
Rule violated
Amount deducted
Appeal process
Deadline for compliance
Appeal & Dispute Handling
Riders/drivers should be able to raise disputes against penalties, upload proofs, and track appeal status through the platform.
Non-Functional Requirements (NFR)
Scalability
System should support millions of riders/drivers and evaluate penalties for large datasets efficiently during monthly batch processing.High Availability
Critical services like rule evaluation, deductions, and notifications should maintain high availability (99.9%+) to avoid financial inconsistencies.Consistency & Accuracy
Financial calculations and deductions must be strongly consistent to prevent duplicate or incorrect penalties.Extensibility
System should support adding new penalty rules and policy types without requiring major architectural changes.Auditability & Compliance
Every rule evaluation, deduction, override, and admin action should be fully auditable for regulatory and legal compliance.
APIs for Penalty/Tax Enforcement System
1. Create Penalty Rule
API
POST /api/v1/rules
Request
{
"ruleName": "Minimum Monthly Ride Rule",
"entityType": "DRIVER",
"condition": {
"metric": "MONTHLY_RIDES",
"operator": "LESS_THAN",
"value": 100
},
"penalty": {
"type": "FIXED",
"amount": 500
},
"evaluationFrequency": "MONTHLY",
"isActive": true
}Response
{
"ruleId": "RULE_12345",
"status": "CREATED",
"createdAt": "2026-05-26T10:00:00Z"
}2. Evaluate User Eligibility for Penalty
API
POST /api/v1/evaluations/run
Request
{
"entityType": "DRIVER",
"entityId": "DRIVER_789",
"evaluationPeriod": "2026-05"
}Response
{
"entityId": "DRIVER_789",
"evaluationPeriod": "2026-05",
"violations": [
{
"ruleId": "RULE_12345",
"metricValue": 72,
"expectedValue": 100,
"penaltyAmount": 500
}
],
"totalPenalty": 500,
"status": "PENALTY_APPLIED"
}3. Fetch Penalty History
API
GET /api/v1/penalties/{entityId}
Response
{
"entityId": "DRIVER_789",
"penalties": [
{
"penaltyId": "PEN_1001",
"ruleId": "RULE_12345",
"amount": 500,
"status": "DEDUCTED",
"createdAt": "2026-05-26T12:00:00Z"
},
{
"penaltyId": "PEN_1002",
"ruleId": "RULE_99999",
"amount": 200,
"status": "WAIVED",
"createdAt": "2026-04-26T12:00:00Z"
}
]
}4. Deduct Penalty from Wallet
API
POST /api/v1/wallets/deduct
Request
{
"entityId": "DRIVER_789",
"penaltyId": "PEN_1001",
"amount": 500,
"currency": "INR"
}Response
{
"transactionId": "TXN_56789",
"walletBalance": 3200,
"status": "SUCCESS"
}5. Raise Penalty Dispute
API
POST /api/v1/disputes
Request
{
"penaltyId": "PEN_1001",
"entityId": "DRIVER_789",
"reason": "Ride count calculation incorrect",
"attachments": [
"s3://proofs/screenshot1.png"
]
}Response
{
"disputeId": "DISP_4567",
"status": "UNDER_REVIEW",
"createdAt": "2026-05-26T13:00:00Z"
}6. Get Evaluation Summary Dashboard
API
GET /api/v1/reports/summary?period=2026-05
Response
{
"period": "2026-05",
"totalDriversEvaluated": 1000000,
"totalPenaltiesApplied": 125000,
"totalAmountCollected": 45000000,
"topViolationReasons": [
{
"rule": "MIN_MONTHLY_RIDES",
"count": 80000
},
{
"rule": "LOW_RATING",
"count": 45000
}
]
}Databases and Schema
```json
{
"users": {
"user_id": "BIGINT",
"user_type": "ENUM(DRIVER, RIDER)",
"name": "VARCHAR",
"avg_rating": "DECIMAL(2,1)",
"total_rides": "BIGINT",
"wallet_balance": "DECIMAL",
"status": "ENUM(ACTIVE, BLOCKED)",
"created_at": "TIMESTAMP"
},
"penalty_rules": {
"rule_id": "BIGINT",
"rule_name": "VARCHAR",
"entity_type": "ENUM(DRIVER, RIDER)",
"metric": "VARCHAR",
"operator": "ENUM(LESS_THAN, GREATER_THAN)",
"threshold_value": "DECIMAL",
"penalty_type": "ENUM(FIXED, PERCENTAGE)",
"penalty_amount": "DECIMAL",
"evaluation_frequency": "ENUM(DAILY, WEEKLY, MONTHLY)",
"is_active": "BOOLEAN",
"created_by": "BIGINT",
"created_at": "TIMESTAMP"
},
"user_metrics": {
"metric_id": "BIGINT",
"user_id": "BIGINT",
"month": "VARCHAR",
"completed_rides": "INT",
"cancelled_rides": "INT",
"avg_rating": "DECIMAL(2,1)",
"online_hours": "INT",
"last_updated_at": "TIMESTAMP"
},
"penalties": {
"penalty_id": "BIGINT",
"user_id": "BIGINT",
"rule_id": "BIGINT",
"metric_value": "DECIMAL",
"expected_value": "DECIMAL",
"penalty_amount": "DECIMAL",
"status": "ENUM(APPLIED, DEDUCTED, WAIVED)",
"evaluation_period": "VARCHAR",
"created_at": "TIMESTAMP"
},
"wallet_transactions": {
"transaction_id": "BIGINT",
"user_id": "BIGINT",
"penalty_id": "BIGINT",
"transaction_type": "ENUM(DEBIT, CREDIT)",
"amount": "DECIMAL",
"balance_after_txn": "DECIMAL",
"transaction_status": "ENUM(SUCCESS, FAILED)",
"created_at": "TIMESTAMP"
},
"disputes": {
"dispute_id": "BIGINT",
"penalty_id": "BIGINT",
"user_id": "BIGINT",
"reason": "TEXT",
"attachment_url": "VARCHAR",
"status": "ENUM(UNDER_REVIEW, APPROVED, REJECTED)",
"resolved_by": "BIGINT",
"resolution_notes": "TEXT",
"created_at": "TIMESTAMP",
"resolved_at": "TIMESTAMP"
},
"audit_logs": {
"audit_id": "BIGINT",
"entity_type": "VARCHAR",
"entity_id": "BIGINT",
"action": "VARCHAR",
"performed_by": "BIGINT",
"old_value": "JSON",
"new_value": "JSON",
"created_at": "TIMESTAMP"
}
}
```
HLD
```text
========================================================
HIGH LEVEL DESIGN (HLD)
========================================================
+----------------------+
| Admin Panel |
+----------+-----------+
|
v
+----------------------+
| Rule Management |
| Service |
+----------+-----------+
|
v
+----------------------+
| Penalty Rules DB |
+----------------------+
+------------+ +----------------------+ +------------------+
| Ride | ----> | Event Ingestion | ----> | Kafka/Event Bus |
| Service | | Service | +--------+---------+
+------------+ +----------------------+ |
|
+------------+ |
| Rating | ----------------------------------------------+
| Service | |
+------------+ |
v
+----------------------+
| Metrics Aggregator |
| Service |
+----------+-----------+
|
v
+----------------------+
| User Metrics DB |
+----------+-----------+
|
v
+----------------------+
| Penalty Evaluation |
| Engine |
+----------+-----------+
|
+--------------------+------------------+
| |
v v
+--------------------------+ +------------------------+
| Penalty Ledger Service | | Notification Service |
+------------+-------------+ +------------+-----------+
| |
v v
+--------------------------+ +------------------------+
| Penalty DB | | Email/SMS/Push |
+------------+-------------+ +------------------------+
|
v
+--------------------------+
| Wallet Service |
+------------+-------------+
|
v
+--------------------------+
| Wallet Transactions DB |
+--------------------------+
========================================================
FLOW DIAGRAM - MONTHLY PENALTY EVALUATION
========================================================
1. Ride Completed
|
v
2. Ride Service emits event to Kafka
|
v
3. Metrics Aggregator consumes events
|
v
4. Update monthly metrics in User Metrics DB
|
v
5. Monthly Scheduler triggers Evaluation Engine
|
v
6. Evaluation Engine fetches:
- Active Rules
- User Metrics
|
v
7. Rule Validation
Example:
completed_rides < 100
|
+---- NO ----> No action
|
+---- YES ---> Generate penalty
|
v
8. Store penalty in Penalty DB
|
v
9. Call Wallet Service
|
v
10. Deduct amount from wallet
|
v
11. Store wallet transaction
|
v
12. Send notification to user
========================================================
FLOW DIAGRAM - DISPUTE HANDLING
========================================================
1. User raises dispute
|
v
2. Dispute Service stores dispute
|
v
3. Admin reviews dispute
|
+---- APPROVED ----+
| |
| v
| Refund penalty
| |
| v
| Update wallet balance
|
+---- REJECTED ----+
|
v
Keep penalty active
|
v
Notify user
========================================================
CORE MICROSERVICES
========================================================
1. Rule Management Service
- Create/update/delete rules
- Rule versioning
2. Metrics Aggregator Service
- Consume ride/rating events
- Aggregate monthly metrics
3. Penalty Evaluation Engine
- Execute rule evaluation jobs
- Generate penalties
4. Penalty Ledger Service
- Maintain immutable penalty history
5. Wallet Service
- Deduct/refund money
- Ensure transactional consistency
6. Notification Service
- SMS/Push/Email alerts
7. Dispute Service
- Dispute lifecycle management
8. Audit Service
- Maintain compliance logs
========================================================
SCALABILITY CONSIDERATIONS
========================================================
1. Kafka partitions by user_id
2. Batch evaluation jobs partitioned by region/user buckets
3. Redis cache for active rules
4. Read replicas for analytics queries
5. Monthly partitioned tables for penalties and transactions
6. Idempotent wallet deduction APIs
7. Retry queues + DLQ for failed deductions
```========================================================
MICROSERVICES AND INTERACTIONS
========================================================
1. API GATEWAY
--------------------------------------------------------
Responsibilities:
- Entry point for all clients
- Authentication & authorization
- Rate limiting
- Request routing
Interacts With:
- Rule Management Service
- Penalty Service
- Dispute Service
- Wallet Service
- Notification Service
2. RULE MANAGEMENT SERVICE
--------------------------------------------------------
Responsibilities:
- Create/update/delete penalty rules
- Enable/disable rules
- Rule versioning
- Rule validation
Database:
- penalty_rules DB
Publishes Events:
- RULE_CREATED
- RULE_UPDATED
- RULE_DELETED
Interacts With:
- Admin Panel
- Penalty Evaluation Engine
- Redis Cache
3. EVENT INGESTION SERVICE
--------------------------------------------------------
Responsibilities:
- Consume ride/rating/cancellation events
- Standardize incoming events
- Push events to Kafka
Consumes From:
- Ride Service
- Rating Service
Publishes To:
- Kafka Topics
4. METRICS AGGREGATOR SERVICE
--------------------------------------------------------
Responsibilities:
- Consume Kafka events
- Aggregate monthly metrics
- Compute:
- completed rides
- cancellation %
- avg ratings
- active hours
Database:
- user_metrics DB
Consumes:
- ride_completed events
- rating_updated events
- cancellation events
Publishes:
- METRICS_UPDATED
5. PENALTY EVALUATION ENGINE
--------------------------------------------------------
Responsibilities:
- Run periodic evaluation jobs
- Fetch active rules
- Evaluate user metrics
- Generate penalties
Consumes:
- METRICS_UPDATED
- Scheduler triggers
Reads From:
- penalty_rules DB
- user_metrics DB
Publishes:
- PENALTY_CREATED
Interacts With:
- Penalty Ledger Service
- Wallet Service
- Notification Service
6. PENALTY LEDGER SERVICE
--------------------------------------------------------
Responsibilities:
- Store immutable penalty history
- Maintain audit trail
- Penalty state management
Database:
- penalties DB
Consumes:
- PENALTY_CREATED
Publishes:
- PENALTY_APPLIED
- PENALTY_WAIVED
Interacts With:
- Wallet Service
- Dispute Service
- Audit Service
7. WALLET SERVICE
--------------------------------------------------------
Responsibilities:
- Deduct penalty amount
- Refund amount on dispute approval
- Maintain financial consistency
- Handle retries/idempotency
Database:
- wallet_transactions DB
Consumes:
- PENALTY_APPLIED
- REFUND_REQUESTED
Publishes:
- PAYMENT_SUCCESS
- PAYMENT_FAILED
Interacts With:
- Penalty Service
- Notification Service
8. NOTIFICATION SERVICE
--------------------------------------------------------
Responsibilities:
- Send push/email/SMS notifications
- Notify about:
- penalties
- refunds
- disputes
- warnings
Consumes:
- PENALTY_CREATED
- PAYMENT_SUCCESS
- DISPUTE_RESOLVED
External Integrations:
- Email provider
- SMS gateway
- Push notification provider
9. DISPUTE SERVICE
--------------------------------------------------------
Responsibilities:
- Create/manage disputes
- Upload proof documents
- Track dispute lifecycle
Database:
- disputes DB
Consumes:
- User dispute requests
Publishes:
- DISPUTE_CREATED
- DISPUTE_APPROVED
- DISPUTE_REJECTED
Interacts With:
- Penalty Ledger Service
- Wallet Service
- Notification Service
10. AUDIT SERVICE
--------------------------------------------------------
Responsibilities:
- Track all admin/system actions
- Maintain compliance logs
- Store immutable audit records
Database:
- audit_logs DB
Consumes:
- RULE_UPDATED
- PENALTY_APPLIED
- DISPUTE_RESOLVED
- WALLET_DEDUCTED
========================================================
SERVICE INTERACTION FLOW
========================================================
Ride Service
|
v
Event Ingestion Service
|
v
Kafka/Event Bus
|
v
Metrics Aggregator Service
|
v
User Metrics DB
|
v
Penalty Evaluation Engine
|
+--------------------+
| |
v v
Penalty Ledger Notification Service
Service
|
v
Wallet Service
|
v
Wallet Transactions DB
|
v
Notification Service
========================================================
ASYNC COMMUNICATION
========================================================
Kafka Topics:
- ride_completed
- ride_cancelled
- rating_updated
- metrics_updated
- penalty_created
- penalty_applied
- payment_success
- dispute_created
- dispute_resolved
========================================================
WHY MICROSERVICE ARCHITECTURE?
========================================================
1. Independent scaling of evaluation engine
2. Wallet service isolated for strong consistency
3. Rule engine can evolve independently
4. Async event-driven processing reduces coupling
5. Easier fault isolation
6. Supports millions of monthly evaluations