caravel/backend/spec/models.md

This file describes the domain model. This description should be translated into standard structs and sqlite schemas in a way that makes sense.

Activity

Activity is an audit log of all actions performed by a user or a worker process. This allows us to trace history to create invoices, synchronize actions to external services, and debug system behavior.

• id - a random activity ID
• created_at - unix timestamp when the activity was created
• activity_type is one of:
  • tenant_created
  • tenant_billing_anchor_updated
  • relay_created
  • relay_updated
  • relay_activated
  • relay_deactivated
  • relay_sync_failed
  • invoice_created
  • invoice_paid
  • invoice_attempted
  • invoice_sent
  • invoice_closed
• identifier is a string identifying the resource being modified. This id in interpreted depending on what the activity_type is.

Tenant

Tenants are customers of the service, identified by a nostr pubkey. Public metadata like name etc are pulled from the nostr network. They also have associated billing information.

• pubkey is the nostr public key identifying the tenant
• nwc_url a nostr wallet connect URL used for paying invoices generated by the system
• created_at unix timestamp identifying tenant creation time
• billing_anchor unix timestamp identifying billing cycle anchor. This gets reset when the tenant has no paid relays and adds (or reactivates) one.

Relay

A relay is a nostr relay owned by a tenant and hosted by the attached zooid instance. Relay subdomains MUST be unique.

• id - a random ID identifying the relay
• tenant - the tenant's pubkey
• schema - the relay's db schema (read_only, calculated based on subdomain + id)
• subdomain - the relay's subdomain
• plan - the relay's plan
• status - new|active|inactive. Only active relays count toward billing.
• sync_error - a string indicating any errors encountered when synchronizing.
• info_name - the relay's name
• info_icon - the relay's icon image URL
• info_description - the relay's description
• policy_public_join - whether to allow non-members to join the relay without an invite code
• policy_strip_signatures - whether to remove signatures when serving events to non-admins
• groups_enabled - whether NIP 29 groups are enabled
• management_enabled - whether NIP 86 management API is enabled
• blossom_enabled - whether blossom file storage is enabled
• livekit_enabled - whether livekit calls are enabled
• push_enabled - whether relay push is enabled

Some attributes persisted to zooid via API have special handling:

• The relay's secret is generated once and persisted to the zooid configuration but isn't stored in the database.
• The relay's host is calculated based on subdomain + RELAY_DOMAIN
• The value of inactive is calculated based on status
• The relay's livekit_* configuration is inferred based on environment variables and livekit_enabled.
• The relay's roles are hard-coded for now.

Invoice

Invoices are generated at the end of a tenant's monthly billing period. The billing module is responsible for creating them, collecting them, and dunning them.

• id - random invoice ID
• tenant - tenant pubkey
• status - pending|paid|closed
• amount is derived as the sum of associated invoice item sats values (not stored as a separate source of truth)
• created_at - unix timestamp for when the invoice was created
• attempted_at - nullable unix timestamp for when collection was last attempted
• error - optional human-readable error from the last failed collection attempt
• closed_at - nullable unix timestamp for when the invoice was closed
• sent_at - nullable unix timestamp for when the invoice was sent via DM
• paid_at - nullable unix timestamp for when the invoice was paid
• bolt11 - a BOLT 11 lightning invoice that can be used to pay the invoice
• period_start - unix timestamp for period start
• period_end - unix timestamp for period end

Invoice Item

Invoice items are attached to an invoice and represent charges for a given relay.

• id - random invoice item ID
• invoice - invoice ID
• relay - relay ID
• sats - amount in satoshis