Skip to content

BSS Setup Data

This folder contains market-specific configuration files for the Battery Swap Service (BSS) model.

Market Organization

Setup data is organized by market with each market in its own subfolder:

Kenya_Nairobi/ - Nairobi, Kenya Market

  • Services, bundles, terms, templates, plans, and account instances
  • Files: bss-nairobi-*-v2.json
  • Status: Deployed with customer instances

Togo_Lome/ - Lome, Togo Market

  • Services, bundles, terms, and templates
  • Files: bss-lome-*-v1.json
  • Documentation: bss-lome-setup.md
  • Status: Ready for deployment

Entity Hierarchy & Naming Convention

Entity Hierarchy

The BSS model follows a strict hierarchy from atomic services to customer instances:

Service (atomic offering)
  ↓
Bundle (service collection by tier: barebone, lux, premium, etc.)
  ↓ (NO period information at this level)
Terms (contract terms, may include period: 7day, 30day, etc.)
  ↓
Plan (Bundle + Terms = complete subscription offering)
  ↓
Plan Instance (customer-specific plan with start/end dates)

Key Principle: Bundles represent tier-based service collections (barebone vs lux) and do NOT contain period information. Subscription periods are managed at the Terms and Plan levels.

Naming Convention

All files follow the pattern: {model}-{market}-{entity_type}-{entity_name}-{version}.json

  • Model prefix: bss (Battery Swap Service)
  • Market component: nairobi, lome (market identifier)
  • Entity type: service, bundle, terms, plan
  • Entity name: Specific identifier (e.g., swap-network, barebone, 7day-standard)
  • Version: v1, v2 (optional for base entities, required for plans)

File Naming Examples by Entity Type

Services (atomic): - bss-nairobi-service-swap-network-v2.json - bss-lome-service-electricity.json

Bundles (tier-based, NO period): - bss-nairobi-bundle-swap-freedom-v2.json - bss-lome-bundle-barebone.json - bss-lome-bundle-lux.json

Terms (contract terms, MAY include period): - bss-nairobi-terms-premium-v2.json - bss-lome-terms-7day-standard.json - bss-lome-terms-30day-standard.json

Plans (bundle + terms + period): - bss-nairobi-plan-monthly-flatfee-v2.json - bss-lome-plan-barebone-7day-v1.json - bss-lome-plan-lux-30day-v1.json

Plan Instances (customer-specific): - bss-nairobi-plan-monthly-flatfee-v2-plan1.json - bss-nairobi-payment-account-monthly-v2-customer001.json

File Structure

Individual Files per Entity

Each entity (service, bundle, terms, plan) is stored in its own JSON file for: - Modularity: Easy to reference, version, and reuse - Git-friendly: Changes isolated to specific entities - Clarity: Self-documenting structure with _meta blocks

Metadata Block

All files include a _meta block documenting the naming pattern:

{
  "_meta": {
    "service_model": "bss",
    "entity_type": "bundle",
    "market": "lome",
    "entity_name": "barebone",
    "version": null,
    "filename_pattern": "{model}-{market}-{entity_type}-{entity_name}.json"
  },
  "id": "bundle-togo-barebone",
  ...
}

Data Validation

  • All files include _meta blocks with filename-metadata binding
  • Schema compliance verified against ABS Platform GraphQL schema
  • No hard-coded values - all data derives from configuration templates