source_intel/ENTITY_VIEW_MAPPING.md

JPA Entity to Database View Mapping for Risk Rules Framework

📋 Overview

This document maps JPA entity classes to their corresponding database views and the risk rules they support. This mapping is essential for the complete 45-rule intelligence framework defined in RISK_RULES_INTOP_OSINT.md.

Status: Partially Implemented
Date: 2025-11-17
Related Issue: #[Current Issue Number]

---

📊 Implementation Status Summary

Category	Total Views	Implemented	Pending	Coverage
V1.30 OSINT Performance Tracking	4	3	1	75%
V1.29 Intelligence Operations	6	0	6	0%
TOTAL NEW VIEWS	10	3	7	30%

---

✅ Implemented Entities (v1.30)

1. ViewPoliticianBehavioralTrends

• Package: com.hack23.cia.model.internal.application.data.politician.impl
• Database View: view_politician_behavioral_trends
• Liquibase Version: v1.30
• Primary Key: Composite (person_id + period_start)
• Columns: 26 fields
• Risk Rules Supported: P-01 through P-24 (All politician behavioral rules)
• Intelligence Purpose: Time-series analysis of individual politician behavioral metrics (absence, effectiveness, rebellion) with automated classification
• Status: ✅ COMPLETE
• Key Metrics:
  • Behavioral metrics: absence_rate, win_rate, rebel_rate
  • Trend indicators: absence_trend, win_rate_trend, rebel_rate_trend
  • Moving averages: 3-month MA for smoothed trend analysis
  • Classifications: attendance_status, effectiveness_status, discipline_status, behavioral_assessment

2. ViewPartyEffectivenessTrends

• Package: com.hack23.cia.model.internal.application.data.party.impl
• Database View: view_party_effectiveness_trends
• Liquibase Version: v1.30
• Primary Key: Composite (party + period_start)
• Columns: 30 fields
• Risk Rules Supported: Pa-01 through Pa-10 (All party-level rules)
• Intelligence Purpose: Monitor party-level performance metrics over time, track win rates, productivity, and collaboration patterns
• Status: ✅ COMPLETE
• Key Metrics:
  • Performance: avg_win_rate, avg_absence_rate, avg_rebel_rate, avg_yes_rate
  • Productivity: documents_produced, motions_count, active_document_authors, votes_per_member
  • Trend indicators: win_rate_trend, absence_trend, member_change
  • Moving averages: ma_4quarter_win_rate, ma_4quarter_absence
  • Classifications: performance_level, productivity_level, effectiveness_assessment

3. ViewRiskScoreEvolution

• Package: com.hack23.cia.model.internal.application.data.rules.impl
• Database View: view_risk_score_evolution
• Liquibase Version: v1.30
• Primary Key: Composite (person_id + assessment_period)
• Columns: 21 fields
• Risk Rules Supported: All 45 rules (cross-cutting risk assessment)
• Intelligence Purpose: Track temporal evolution of risk scores with severity classification and trend analysis
• Status: ✅ COMPLETE
• Key Metrics:
  • Risk metrics: risk_score, prev_risk_score, risk_score_change
  • Contributing factors: absence_rate, win_rate, rebel_rate, violation_count, violation_categories
  • Classifications: risk_severity, risk_trend, severity_transition
  • Assessment: risk_assessment (CRITICAL, HIGH, MODERATE, LOW, MINIMAL)

---

🔶 Pending Entity Implementations

v1.30 OSINT Performance Tracking Views (3 remaining)

2. ViewPartyEffectivenessTrends

• Package: com.hack23.cia.model.internal.application.data.party.impl
• Database View: view_party_effectiveness_trends
• Liquibase Version: v1.30
• Primary Key: Composite (party + period_start)
• Estimated Columns: 30+
• Risk Rules Supported: Pa-01 through Pa-10 (All party-level rules)
• Intelligence Purpose: Monitor party-level performance metrics over time, track win rates, productivity, and collaboration patterns
• Key Metrics:
  • Performance: avg_win_rate, avg_absence_rate, avg_rebel_rate
  • Productivity: documents_produced, motions_count, votes_per_member
  • Trend indicators: win_rate_trend, absence_trend, member_change
  • Classifications: performance_level, productivity_level
• Status: 🔶 PENDING - Entity class needs to be created

3. ViewRiskScoreEvolution

• Package: com.hack23.cia.model.internal.application.data.rules.impl
• Database View: view_risk_score_evolution
• Liquibase Version: v1.30
• Primary Key: Composite (person_id + assessment_period)
• Estimated Columns: 22
• Risk Rules Supported: All 45 rules (cross-cutting risk assessment)
• Intelligence Purpose: Track temporal evolution of risk scores with severity classification and trend analysis
• Key Metrics:
  • Risk metrics: risk_score, prev_risk_score, risk_score_change
  • Contributing factors: absence_rate, win_rate, rebel_rate, violation_count
  • Classifications: risk_severity, risk_trend, severity_transition
  • Assessment: risk_assessment (CRITICAL, HIGH, MODERATE, LOW, MINIMAL)
• Status: 🔶 PENDING - Entity class needs to be created

4. ViewCommitteeProductivityMatrix

• Package: com.hack23.cia.model.internal.application.data.committee.impl
• Database View: view_committee_productivity_matrix
• Liquibase Version: v1.30
• Primary Key: Composite (committee_code + period_start)
• Estimated Columns: 28
• Risk Rules Supported: C-01 through C-04 (Committee performance rules)
• Intelligence Purpose: Quarterly committee productivity metrics with comparative analysis and benchmarking
• Key Metrics:
  • Productivity: total_documents, committee_reports, documents_per_member
  • Trend indicators: document_change, document_change_pct, ma_4quarter_documents
  • Benchmarking: vs_average, vs_average_pct, period_median_documents
  • Classifications: productivity_level, productivity_trend, productivity_assessment
• Status: 🔶 IN PROGRESS - Entity class being created

---

v1.29 Intelligence Operations Enhancement Views (6 remaining)

5. ViewRiksdagenPartyMomentumAnalysis

• Package: com.hack23.cia.model.internal.application.data.party.impl
• Database View: view_riksdagen_party_momentum_analysis
• Liquibase Version: v1.29
• Primary Key: Composite (party + year + quarter)
• Estimated Columns: 14
• Risk Rules Supported: Pa-01, Pa-02, Pa-07 (Party momentum and stability)
• Intelligence Purpose: Detect momentum shifts in party support with acceleration/deceleration patterns
• Key Metrics:
  • Momentum: momentum, acceleration, prev_quarter_rate
  • Smoothing: moving_avg_4q, volatility
  • Classifications: trend_direction, stability_classification, intelligence_assessment
• Status: 🔶 PENDING - Entity class needs to be created

6. ViewRiksdagenCoalitionAlignmentMatrix

• Package: com.hack23.cia.model.internal.application.data.party.impl
• Database View: view_riksdagen_coalition_alignment_matrix
• Liquibase Version: v1.29
• Primary Key: Composite (party_1 + party_2)
• Estimated Columns: 12
• Risk Rules Supported: Pa-03, Pa-08 (Coalition formation and stability)
• Intelligence Purpose: Measure voting alignment between party pairs for coalition formation prediction
• Key Metrics:
  • Alignment: shared_votes, aligned_votes, opposed_votes, alignment_rate
  • Analysis: coalition_likelihood, bloc_relationship
  • Intelligence: intelligence_comment, years_observed
• Status: 🔶 PENDING - Entity class needs to be created

7. ViewRiksdagenVotingAnomalyDetection

• Package: com.hack23.cia.model.internal.application.data.politician.impl
• Database View: view_riksdagen_voting_anomaly_detection
• Liquibase Version: v1.29
• Primary Key: Composite (person_id + party)
• Estimated Columns: 13
• Risk Rules Supported: P-03, P-05, P-13 (Rebellion and discipline)
• Intelligence Purpose: Detect voting anomalies and party discipline deviations
• Key Metrics:
  • Voting patterns: total_votes, aligned_votes, opposed_votes
  • Discipline: party_discipline_score, rebellion_rate, unanimous_deviations
  • Classifications: discipline_classification, defection_risk_assessment
• Status: 🔶 PENDING - Entity class needs to be created

8. ViewRiksdagenPoliticianInfluenceMetrics

• Package: com.hack23.cia.model.internal.application.data.politician.impl
• Database View: view_riksdagen_politician_influence_metrics
• Liquibase Version: v1.29
• Primary Key: person_id
• Estimated Columns: 10
• Risk Rules Supported: P-20, P-21 (Network influence and broker roles)
• Intelligence Purpose: Basic network centrality and influence scoring
• Key Metrics:
  • Network: network_connections, cross_party_bridges
  • Centrality: normalized_centrality, connectivity_level
  • Classification: broker_classification, influence_score, influence_assessment
• Status: 🔶 PENDING - Entity class needs to be created

9. ViewRiksdagenCrisisResilienceIndicators

• Package: com.hack23.cia.model.internal.application.data.politician.impl
• Database View: view_riksdagen_crisis_resilience_indicators
• Liquibase Version: v1.29
• Primary Key: person_id
• Estimated Columns: 13
• Risk Rules Supported: P-08, P-22 (Performance under pressure)
• Intelligence Purpose: Assess politician performance during crisis periods vs normal periods
• Key Metrics:
  • Crisis performance: crisis_period_votes, crisis_absence_rate, crisis_party_discipline
  • Normal baseline: normal_period_votes, normal_absence_rate
  • Analysis: absence_rate_change, resilience_score
  • Classification: resilience_classification, pressure_performance_assessment
• Status: 🔶 PENDING - Entity class needs to be created

10. ViewRiksdagenIntelligenceDashboard

• Package: com.hack23.cia.model.internal.application.data.impl
• Database View: view_riksdagen_intelligence_dashboard
• Liquibase Version: v1.29
• Primary Key: None (single-row summary view, timestamp-based)
• Estimated Columns: 3
• Risk Rules Supported: All rules (summary dashboard)
• Intelligence Purpose: Executive summary dashboard with overall stability and coalition assessments
• Key Metrics:
  • stability_assessment: Overall political stability indicator
  • coalition_assessment: Coalition formation likelihood and status
  • intelligence_report_timestamp: Report generation time
• Status: 🔶 PENDING - Entity class needs to be created

---

📝 Implementation Guidelines

Entity Class Template

All view entities should follow this pattern:

package com.hack23.cia.model.internal.application.data.[package].impl;

import java.io.Serializable;
import java.math.BigDecimal;
import java.util.Date;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Table;
import javax.persistence.Temporal;
import javax.persistence.TemporalType;
import org.apache.commons.lang3.builder.EqualsBuilder;
import org.apache.commons.lang3.builder.HashCodeBuilder;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;

/**
 * JPA entity for [view_name] database view.
 * 
 * Intelligence Purpose: [purpose description]
 * Created by: Liquibase [version]
 * Risk Rules Supported: [rule numbers]
 */
@Entity(name = "[ClassName]")
@Table(name = "[view_name]")
public class [ClassName] implements Serializable {
    
    private static final long serialVersionUID = 1L;
    
    // ID fields marked with @Id
    // Other fields with @Column
    // Dates with @Temporal
    // BigDecimal for numeric fields with precision
    
    // Default constructor
    // Getters and setters
    // equals(), hashCode(), toString() using Commons Lang builders
}

Key Annotations

• @Entity(name = "ClassName"): JPA entity marker
• @Table(name = "view_name"): Database view name (lowercase with underscores)
• @Id: Primary key fields (may be composite)
• @Column(name = "column_name"): Column mapping
• @Temporal(TemporalType.DATE|TIMESTAMP): For Date fields
• For BigDecimal: @Column(name = "col", precision = X, scale = Y)

Composite Keys

For views with composite keys (multiple @Id fields), the combination of all @Id fields forms the primary key. No separate @IdClass is needed if using simple types.

---

🔗 Integration with Risk Rules Framework

Rule-to-View Mapping

Rule Category	Primary Views	Secondary Views
Politician Rules (P-01 to P-24)	ViewPoliticianBehavioralTrends, ViewRiksdagenVotingAnomalyDetection	ViewRiksdagenPoliticianInfluenceMetrics, ViewRiksdagenCrisisResilienceIndicators
Party Rules (Pa-01 to Pa-10)	ViewPartyEffectivenessTrends, ViewRiksdagenPartyMomentumAnalysis	ViewRiksdagenCoalitionAlignmentMatrix
Committee Rules (C-01 to C-04)	ViewCommitteeProductivityMatrix	-
Ministry Rules (M-01 to M-04)	(v1.31 - not yet implemented)	-
Cross-Cutting	ViewRiskScoreEvolution, ViewRiksdagenIntelligenceDashboard	-

---

📊 Technical Specifications

Data Types Mapping

SQL Type	Java Type	Notes
VARCHAR	String	Use @Column(length = X)
INTEGER	Integer or Long	Use Long for counts
NUMERIC(p,s)	BigDecimal	Use @Column(precision = p, scale = s)
DATE	Date	Use @Temporal(TemporalType.DATE)
TIMESTAMP	Date	Use @Temporal(TemporalType.TIMESTAMP)
BOOLEAN	Boolean	-

Naming Conventions

• Entity Class: PascalCase, e.g., ViewPoliticianBehavioralTrends
• Table Name: snake_case, e.g., view_politician_behavioral_trends
• Column Name: snake_case, e.g., avg_absence_rate
• Field Name: camelCase, e.g., avgAbsenceRate

---

🚀 Next Steps

Priority 1: Complete v1.30 Views (Required for Core Risk Assessment)

1. ViewRiskScoreEvolution - Critical for all 45 rules
2. ViewCommitteeProductivityMatrix - Committee rules (C-01 to C-04)
3. ViewPartyEffectivenessTrends - Party rules (Pa-01 to Pa-10)

Priority 2: Complete v1.29 Intelligence Views (Enhanced Analytics)

4. ViewRiksdagenVotingAnomalyDetection - Critical for P-03, P-05, P-13
5. ViewRiksdagenPartyMomentumAnalysis - Party momentum analysis
6. ViewRiksdagenCoalitionAlignmentMatrix - Coalition formation
7. ViewRiksdagenPoliticianInfluenceMetrics - Network analysis
8. ViewRiksdagenCrisisResilienceIndicators - Crisis performance
9. ViewRiksdagenIntelligenceDashboard - Executive summary

Priority 3: Verification and Testing

• Update persistence.xml with all new entity registrations
• Build and test entity mappings
• Verify query performance
• Test integration with rules engine
• Document usage examples

---

📚 Related Documentation

• RISK_RULES_INTOP_OSINT.md - Complete 45-rule framework
• DATABASE_VIEW_INTELLIGENCE_CATALOG.md - View catalog and usage patterns
• LIQUIBASE_CHANGELOG_INTELLIGENCE_ANALYSIS.md - Changelog evolution
• DATA_MODEL.md - Database schema and relationships
• service.data.impl/README-SCHEMA-MAINTENANCE.md - Schema maintenance guidelines

---

📝 Notes

• All views are READ-ONLY (database views, not tables)
• No @Immutable annotation needed (causes module dependency issues)
• Views are materialized or standard based on Liquibase definitions
• Composite keys use multiple @Id annotations on entity fields
• Use Apache Commons Lang builders for equals/hashCode/toString

Last Updated: 2025-11-17
Maintainer: CIA Intelligence Operations Team