ERD vs GraphQL Schema Comparison Analysis¶

2026-04-07

Overview¶

This document compares the entities-erd.puml diagram against the corrected abs.graphql schema to identify inconsistencies and alignment issues.

🔴 CRITICAL INCONSISTENCIES FOUND¶

1. CommonTerms Fields Mismatch¶

ERD shows:

monthly_quota : Float!

Schema shows (CORRECTED):

# REMOVED: monthly_quota field - conceptually invalid at template level
# monthly_quota: Float!

Status: ✅ ERD needs update - Schema correction is correct, ERD shows outdated field

2. ServicePlanTemplate Currency Field Missing in ERD¶

ERD shows:

# Missing billing_currency field

Schema shows (CORRECTED):

billing_currency: String!                # ISO 4217 currency code (e.g., USD, KES)

Status: 🔴 ERD needs update - Missing critical new field

3. ServicePlan Currency Field Discrepancy¶

ERD shows:

currency : String!       # Must match template.contract_terms.billing_currency

Schema shows (CORRECTED):

# REMOVED: ServicePlan-level currency field - should be derived from template
# currency: String!

Status: 🔴 ERD needs update - Field removed from schema, should be derived

4. CommonState Fields Mismatch¶

ERD shows:

billing_balance : Float!
total_services : Int!
active_services : Int!

Schema shows (CORRECTED):

# REMOVED: billing_balance field - duplicates PaymentAccount.balance
# REMOVED: Service count fields - can be computed from ServiceState arrays
# billing_balance: Float!
# total_services: Int!
# active_services: Int!

Status: 🔴 ERD needs update - All three fields removed from schema

5. AgentConfig Version Field Duplication¶

ERD shows:

version : String!
agent_version : String!  # e.g., "1.0.0"

Schema shows (CORRECTED):

version: String!
# REMOVED: agent_version field - duplicates version field above
# agent_version: String!

Status: 🔴 ERD needs update - Duplicate field removed from schema

6. ServiceAccount Usage Summary Field¶

ERD shows:

usage_summary : JSON!

Schema shows (CORRECTED):

# REMOVED: usage_summary field - duplicates structured service_states data
# usage_summary: JSON!

Status: 🔴 ERD needs update - Field removed from schema

7. PaymentAccount Audit Fields Missing in ERD¶

ERD shows:

created_at : DateTime!
updated_at : DateTime!

Schema shows:

created_at: DateTime!
updated_at: DateTime!

Status: ✅ Both aligned - ERD correctly shows audit fields

✅ CORRECTLY ALIGNED ELEMENTS¶

1. Service Entity Structure¶

Both show identical field structure
Both include usage_unit_price for top-up calculations
Asset type enumeration correctly represented

2. ServiceBundle Entity¶

Identical structure in both ERD and schema
Services array relationship correctly modeled
Audit fields properly aligned

3. ServiceState Embedded Structure¶

Both correctly show embedded nature (no separate ID)
service_id, current_asset, used, quota fields match
Nullable current_asset properly represented

4. MealyFSM Structure¶

All fields correctly aligned
initial_state field properly shown in both
Embedded transitions structure matches

5. Location and PhysicalAddress¶

Complete field alignment
Embedded relationship correctly modeled
Optional fields properly represented

🔴 REQUIRED ERD UPDATES¶

Priority 1 - Critical Schema Alignment¶

Add billing_currency to ServicePlanTemplate
Remove currency from ServicePlan
Remove monthly_quota from CommonTerms
Remove billing_balance, total_services, active_services from CommonState
Remove agent_version from AgentConfig
Remove usage_summary from ServiceAccount

Priority 2 - Documentation Updates¶

Update relationship notes to reflect currency derivation
Add comments explaining removed fields for developer reference
Update architecture notes about template-level currency enforcement

📋 RECOMMENDED ERD CORRECTIONS¶

ServicePlanTemplate Updates¶

ENTITY ServicePlanTemplate {
  + id : ID PK
  --
  name : String!
  description : String!
  version : String!
  status : String!

  # ========== COUNTRY & LEGAL JURISDICTION ==========
  country_code : String!
  legal_jurisdiction : String!
  billing_currency : String!   # NEW: ISO 4217 currency code

  contract_terms : CommonTerms FK
  service_cycle_fsm : MealyFSM FK
  payment_cycle_fsm : MealyFSM FK
  agent_config : AgentConfig FK
  created_at : DateTime!
  updated_at : DateTime!
  created_by : String!
  change_log : TemplateChange[]
}

CommonTerms Updates¶

ENTITY CommonTerms {
  + id : ID PK
  --
  service_name : String!
  service_description : String!
  service_duration_days : Int!
  billing_cycle : String!
  monthly_fee : Float!
  deposit_amount : Float!
  # REMOVED: monthly_quota : Float!
  cancellation_notice_days : Int!
  early_termination_fee : Float?
  refund_policy : String!
  liability_limit : Float?
  insurance_required : Boolean!
  damage_deposit : Float?
  governing_law : String!
  dispute_resolution : String!
}

ServicePlan Updates¶

ENTITY ServicePlan {
  + id : ID PK
  --
  customer_id : ID!
  template_id : ID FK
  template_version : String!

  # REMOVED: currency : String!  # Now derived from template.billing_currency

  plan_state : CommonState
  service_state : String!
  payment_state : String!
  agent_state : JSON!
  service_account : ServiceAccount FK
  payment_account : PaymentAccount FK
  created_at : DateTime!
  updated_at : DateTime!
}

CommonState Updates¶

EMBEDDED CommonState <<embedded>> {
  status : String!
  --
  last_billed_at : DateTime?
  next_bill_at : DateTime?
  # REMOVED: billing_balance : Float!
  # REMOVED: total_services : Int!
  # REMOVED: active_services : Int!
}

AgentConfig Updates¶

ENTITY AgentConfig {
  + id : ID PK
  --
  name : String!
  version : String!
  description : String!
  agent_type : String!
  # REMOVED: agent_version : String!
  agent_params : JSON!
  created_at : DateTime!
  updated_at : DateTime!
  created_by : String!
}

ServiceAccount Updates¶

ENTITY ServiceAccount {
  + id : ID PK
  --
  status : String!
  service_bundle : ServiceBundle FK
  service_states : ServiceState[]
  service_history : ServiceAction[]
  # REMOVED: usage_summary : JSON!
  created_at : DateTime!
  updated_at : DateTime!
}

🎯 NEXT STEPS¶

Update ERD File: Apply all corrections listed above
Validate Relationships: Ensure FK relationships reflect currency derivation
Update Architecture Notes: Document removed fields and their rationale
Sync Documentation: Ensure other architectural docs reflect these changes
Developer Communication: Inform team about ERD-schema alignment

📊 SUMMARY¶

Total Entities Checked: 12
Entities Requiring Updates: 6
Critical Misalignments: 6
Fields Removed from Schema: 8
New Fields Added to Schema: 1 (billing_currency)

Recommendation: Update ERD immediately to maintain architectural documentation accuracy and developer alignment.