Schema Alignment Developer Guide¶

Overview¶

This guide documents the schema corrections applied to the ABS Platform and provides guidance for developers working with the updated GraphQL schema and setup data.

✅ Schema Corrections Applied¶

1. Currency Architecture Redesign¶

Problem: Currency definition was split inconsistently between template and plan levels.

Solution Applied:

# ServicePlanTemplate (NEW)
type ServicePlanTemplate {
  country_code: String!
  legal_jurisdiction: String!
  billing_currency: String!    # ✅ NEW: Currency defined at template level
  # ... other fields
}

# ServicePlan (UPDATED) 
type ServicePlan {
  # REMOVED: currency field - now derived from template.billing_currency
  # currency: String!
  # ... other fields
}

Developer Impact: - ✅ All currency information derives from template.billing_currency - ✅ ServicePlan resolvers must access currency via template reference - ✅ Setup data templates must include billing_currency field

2. CommonTerms Field Cleanup¶

Problem: monthly_quota field was conceptually invalid at template level.

Solution Applied:

type CommonTerms {
  service_name: String!
  service_description: String!
  billing_cycle: String!
  monthly_fee: Float!
  deposit_amount: Float!

  # REMOVED: monthly_quota field - conceptually invalid
  # monthly_quota: Float!

  cancellation_notice_days: Int!
  # ... other fields
}

Developer Impact: - ✅ Setup data files remove monthly_quota from all CommonTerms instances - ✅ Quota management handled at ServiceState level within bundles - ✅ Individual services define usage quotas, not template-level global quota

3. CommonState Redundancy Elimination¶

Problem: Multiple fields duplicated data from other entities.

Solution Applied:

type CommonState {
  status: String!
  last_billed_at: DateTime
  next_bill_at: DateTime

  # REMOVED: Redundant fields that duplicate other entity data
  # billing_balance: Float!      # Duplicated PaymentAccount.balance
  # total_services: Int!         # Can be computed from service_states.length
  # active_services: Int!        # Can be computed from service_states
}

Developer Impact: - ✅ Use PaymentAccount.balance for all balance operations - ✅ Compute service counts dynamically from ServiceAccount.service_states arrays - ✅ Remove redundant fields from all setup data plan_state objects

4. AgentConfig Version Consolidation¶

Problem: Duplicate version fields created confusion.

Solution Applied:

type AgentConfig {
  id: ID!
  name: String!
  version: String!               # ✅ Single authoritative version field
  description: String!
  agent_type: String!

  # REMOVED: Duplicate version field
  # agent_version: String!

  agent_params: JSON @domainSpecific
  # ... other fields
}

Developer Impact: - ✅ Use single version field for all agent versioning - ✅ Remove agent_version from setup data and inputs - ✅ Update agent configuration references to use consolidated versioning

5. ServiceAccount Data Structure Cleanup¶

Problem: usage_summary field duplicated structured data.

Solution Applied:

type ServiceAccount {
  id: ID!
  status: String!
  service_bundle: ServiceBundle!
  service_states: [ServiceState!]!    # ✅ Structured usage data
  service_history: [ServiceAction!]!

  # REMOVED: Redundant summary field
  # usage_summary: JSON!              # Duplicated service_states data

  created_at: DateTime!
  updated_at: DateTime!
}

Developer Impact: - ✅ Query service_states for all usage information - ✅ Compute usage summaries dynamically from structured data - ✅ Remove usage_summary from all setup data service accounts

📋 Setup Data Updates Applied¶

BSS Setup Data Files Updated¶

bss-common-terms.json:
✅ Removed monthly_quota from all 3 term entries
✅ Maintained all other contract term fields
nairobi-monthly-flatfee-v1.json:
✅ Added "billing_currency": "KES" to template
✅ Maintained country_code and legal_jurisdiction
nairobi-monthly-flatfee-v1-plan1.json:
✅ Removed currency from service_plan object
✅ Removed billing_balance, total_services, active_services from plan_state
✅ Removed usage_summary from service_account

Sample Data Files Updated¶

service_plan_templates.json:
✅ Changed embedded objects to ID references (contract_terms_id, service_cycle_fsm_id, etc.)
✅ Added required fields: country_code, legal_jurisdiction, billing_currency
service_plans.json:
✅ Removed redundant fields from plan_state arrays
✅ Maintained essential state tracking fields
service_accounts.json:
✅ Removed usage_summary field
✅ Maintained structured service_states arrays

🔧 Developer Guidelines¶

Working with Currency¶

// ✅ CORRECT: Access currency through template
const currency = servicePlan.template.billing_currency;

// ❌ INCORRECT: Direct currency access (field removed)
// const currency = servicePlan.currency;

Computing Service Metrics¶

// ✅ CORRECT: Compute from service_states
const totalServices = serviceAccount.service_states.length;
const activeServices = serviceAccount.service_states.filter(s => s.quota > 0).length;

// ❌ INCORRECT: Access from plan_state (fields removed)
// const totalServices = servicePlan.plan_state.total_services;

Working with Balance Information¶

// ✅ CORRECT: Use PaymentAccount as single source of truth
const balance = servicePlan.payment_account.balance;

// ❌ INCORRECT: Access from CommonState (field removed)
// const balance = servicePlan.plan_state.billing_balance;

Agent Version Management¶

// ✅ CORRECT: Use single version field
const agentVersion = agentConfig.version;

// ❌ INCORRECT: Use duplicate field (removed)
// const agentVersion = agentConfig.agent_version;

🎯 GraphQL Resolver Implications¶

Template Resolvers¶

type ServicePlanTemplate {
  # Resolvers must handle new billing_currency field
  billing_currency: String!
}

ServicePlan Resolvers¶

type ServicePlan {
  # Currency resolver must derive from template
  currency: String! # Computed field - resolves template.billing_currency
}

CommonState Resolvers¶

type CommonState {
  # Computed fields for removed data
  billing_balance: Float!   # Computed from PaymentAccount.balance
  total_services: Int!      # Computed from service_states.length
  active_services: Int!     # Computed from service_states filter
}

🧪 Testing Implications¶

Schema Validation Tests¶

✅ Validate templates include required billing_currency
✅ Ensure ServicePlan currency resolution works correctly
✅ Test computed field calculations for service counts and balances

Data Migration Tests¶

✅ Verify setup data loads without schema violations
✅ Test FK reference resolution for template relationships
✅ Validate removed fields don't appear in API responses

Integration Tests¶

✅ Test end-to-end ServicePlan creation with corrected schema
✅ Verify currency inheritance from template to plan
✅ Test dynamic computation of usage and balance metrics

📁 File Reference Quick List¶

Updated Setup Data Files¶

models/battery-swap/setup-data/
├── bss-common-terms.json              # ✅ Removed monthly_quota
├── nairobi-monthly-flatfee-v1.json    # ✅ Added billing_currency
└── nairobi-monthly-flatfee-v1-plan1.json # ✅ Removed redundant fields

models/samples/abs/types/
├── service_plan_templates.json        # ✅ Fixed FK references
├── service_plans.json                 # ✅ Removed redundant plan_state fields
└── service_accounts.json              # ✅ Removed usage_summary

Schema Reference Files¶

schema/abs.graphql                     # ✅ Corrected schema with commented fields
diagrams/entities-erd.puml             # ❌ Needs update to match schema
schema/SCHEMA_ANALYSIS.md              # ✅ Detailed analysis of corrections
models/MODELS_SCHEMA_COMPATIBILITY.md  # ✅ Compatibility analysis

🚀 Next Steps for Developers¶

Review Schema Changes: Understand field removals and additions
Update Resolvers: Implement currency derivation and computed fields
Test Data Loading: Verify updated setup data loads correctly
Update ERD: Sync entity diagram with corrected schema
Documentation: Update API docs to reflect schema changes

Status: ✅ SCHEMA ALIGNMENT COMPLETE Setup Data: ✅ FULLY COMPLIANT Developer Impact: 📋 RESOLVER UPDATES REQUIRED

For additional context, see: - Models Schema Compatibility Archive - Historical schema issues (resolved) - BSS Model Status - Current BSS implementation status