PlanSignal — Spec Sheet

[ DOWNLOAD DATASHEET ]

Inputs

• Billing events synced from an external payment provider
• Internal plan mappings defined by the operator
• Optional account metadata written by your system
• Account, customer, or subject identifier used for lookup

Outputs

• Account status such as active, canceled, or past_due
• Plan identifier
• Derived entitlement facts
• Read-time JSON response for application evaluation

Guarantees

• Returns stored plan state as of read time
• Does not mutate state on read
• Does not execute side effects on read
• Deterministic for a given stored state

Non-guarantees

• Freshness of billing data
• Accuracy or availability of the upstream billing provider
• Correctness of operator-defined plan mappings
• Consistency across distributed systems
• Authorization correctness
• Security, safety, compliance, or revenue outcomes

Invariants

• Plan state is not authorization
• Entitlement facts are not enforcement
• Absence of a restriction is not permission
• Returned state is application-evaluated

Failure modes

• Billing sync missing → stale or incomplete state
• Webhook delivery failure → lagging state
• Duplicate or out-of-order events without idempotency
• Database or network failure
• Plan mapping misconfiguration
• Application treats emitted state as automatic permission

Performance characteristics

• Read latency: typically a PostgreSQL point lookup
• Concurrency: limited by your PostgreSQL connection pool and indexes
• Caching: not included; implement in your application if required
• Recommended: keep lookup paths indexed by account or subject identifier

Out of scope

• Authentication
• Authorization
• Request handling
• Request blocking
• Feature gating enforcement
• Billing collection or charging
• Background execution
• Policy definition

Implementation details

• Language: TypeScript (Node.js)
• Interface: HTTP or embedded application call depending on deployment
• Database: PostgreSQL
• Deployment: self-hosted service or embedded local component