PlanSignal — Spec Sheet
Primitive type: Plan & billing state emitter
Execution model: Read-time only
Hosting model: Self-hosted
Determinism: Deterministic given stored state
Inputs
- Billing events synced from an external payment provider
- Internal plan mappings defined by the operator
- Optional account metadata written by your system
Outputs
- Account status (active, canceled, past_due, etc.)
- Plan identifier
- Derived entitlement state
Guarantees
- Returns stored state as of read time
- Does not mutate state on read
- Does not execute side effects
Non-guarantees
- Freshness of billing data
- Accuracy of upstream billing provider
- Consistency across distributed systems
- Authorization correctness
- Security or safety outcomes
Invariants
- Absence of a restriction is not permission
- Plan state ≠ authorization
- Returned state is advisory only
Failure modes
- Billing sync missing → stale or incomplete state
- Webhook delivery failure → lagging state
- Duplicate/out-of-order events without idempotency
- Database or network failure
- Plan mapping misconfiguration
Performance characteristics
- Read latency: typically a single PostgreSQL read (workload-dependent)
- Concurrency: limited by your PostgreSQL connection pool and indexes
- Caching: not included (implement in your system if required)
- Recommended: co-locate with your application database to reduce network variance
Out of scope
- Authentication
- Authorization
- Request handling
- Blocking requests
- Background execution
- Policy definition
Implementation details
- Language: TypeScript (Node.js)
- Interface: Direct function calls
- Database: PostgreSQL
- Deployment: Embedded or local service