Policy Admin

The configuration backbone — manages parties, accounts, products, plan designs, rule sets, and market profiles used by Enrollment and other services.

Overview

Policy Admin is the system of record for all insurance product configuration. It defines what products exist, what benefit rules apply at each version, and how those products are structured for different market segments. All other services that need to know "what does this plan cover and at what rate?" consult Policy Admin.

The service models a clear hierarchy: a Party is any person or organisation (member, employer, provider, broker). An Account groups parties for billing and relationship management. A Product represents an insurance product line with versioned ProductVersion records. Each version carries RuleSet and Rule records consumed by the Enrollment rule engine. MarketProfile records capture market segment-specific overrides. FieldDefinition records describe configurable fields for product versions, enabling flexible product design without schema changes.

Responsibilities

• Manage the party master (individuals, organisations, groups) and their roles
• Manage accounts and account contacts
• Define and version insurance products with activation/deactivation lifecycle
• Manage rule sets and individual rules per product version for underwriting enforcement
• Support config bundle deployment (validate → deploy) for packaged product releases
• Manage market profiles with versioned configurations per market segment
• Define field definitions for configurable product attributes
• Serve internal lookups for rule sets, parties, market profiles, and field definitions

Database

Schema: policy_admin

Table	Purpose
parties	Person and organisation records (members, employers, brokers, providers)
party_roles	Role assignments linking parties to accounts (contact, subscriber, dependent)
accounts	Account records grouping parties for billing and management
products	Insurance product definitions
product_versions	Versioned snapshots of product configuration
rule_sets	Named collections of underwriting rules per product version
rules	Individual rule conditions and outcomes
rule_evaluations	Audit log of rule evaluation results
market_profiles	Market segment configurations
field_definitions	Configurable field specifications per product version

API Routes

Method	Path	Auth	Description
POST	/parties	JWT	Create a party
GET	/parties	JWT	List parties
GET	/parties/{locator}	JWT	Get party by locator
PATCH	/parties/{locator}	JWT	Update party details
GET	/parties/{locator}/roles	JWT	List roles for a party
POST	/accounts	JWT	Create an account
GET	/accounts	JWT	List accounts
GET	/accounts/{locator}	JWT	Get account by locator
PATCH	/accounts/{locator}	JWT	Update account
PATCH	/accounts/{locator}/billing-level	JWT	Set billing level
POST	/accounts/{locator}/contacts	JWT	Add a contact to an account
GET	/accounts/{locator}/contacts	JWT	List contacts for an account
PATCH	/accounts/{locator}/contacts/{contactLocator}	JWT	Update a contact
DELETE	/accounts/{locator}/contacts/{contactLocator}	JWT	Remove a contact
POST	/accounts/{locator}/number/generate	JWT	Generate account display number
POST	/products	JWT	Create a product
GET	/products	JWT	List products
GET	/products/{locator}	JWT	Get product by locator
PATCH	/products/{locator}	JWT	Update product
PATCH	/products/{locator}/activate	JWT	Activate a product
PATCH	/products/{locator}/deactivate	JWT	Deactivate a product
POST	/products/{locator}/versions	JWT	Create a product version
GET	/products/{locator}/versions/{version}	JWT	Get a specific product version
GET	/products/{locator}/versions	JWT	List product versions
PATCH	/products/{locator}/versions/{version}	JWT	Update a version
PATCH	/products/{locator}/versions/{version}/publish	JWT	Publish a version
POST	/products/{locator}/versions/{version}/rule-sets	JWT	Create a rule set
GET	/products/{locator}/versions/{version}/rule-sets	JWT	List rule sets for a version
GET	/products/{locator}/versions/{version}/rule-sets/{name}	JWT	Get a named rule set
PUT	/products/{locator}/versions/{version}/rule-sets/{name}/rules	JWT	Replace all rules in a rule set
PATCH	/rules/{locator}	JWT	Update a single rule
POST	/config/validate	JWT	Validate a config bundle
POST	/config/deploy	JWT	Deploy a config bundle
GET	/config/{productLocator}/versions/{version}/download	JWT	Download a config bundle
GET	/market-profiles	JWT	List market profiles
POST	/market-profiles	JWT	Create a market profile
GET	/market-profiles/{code}	JWT	Get market profile by code
GET	/market-profiles/{code}/versions/{version}	JWT	Get a market profile version
PATCH	/market-profiles/{code}/versions/{version}/publish	JWT	Publish a market profile version
GET	/internal/products/{productLocator}/versions/{version}/rulesets/{name}	Internal	Fetch rule set for Enrollment
GET	/internal/parties/{locator}	Internal	Fetch party for Notifications
GET	/internal/market-profiles/{code}/current	Internal	Fetch current market profile
GET	/internal/product-versions/{id}/fields	Internal	Fetch field definitions for a version

Events

Publishes

Policy Admin does not publish Kafka events.

Consumes

Policy Admin does not consume Kafka events.

Dependencies

Policy Admin has no runtime service dependencies. It is a dependency of Enrollment, Claims, Billing, Provider, Notifications, Broker API, and Group Scheme Service.

Key Design Decisions

Config bundle deployment: Rather than editing rules and product attributes through individual API calls, operators can assemble a full configuration bundle (product + versions + rule sets) as a YAML/JSON document, validate it via POST /config/validate, then atomically deploy it with POST /config/deploy. This makes product releases reproducible and auditable.

Versioned products: Product configuration is immutable once a version is published. Enrollment always references a specific ProductVersion, ensuring that in-force policies are always adjudicated against the rules that were in effect when they were underwritten.