Documentation

Architecture

How Astro, Phoenix, Neon, Oban, and provider adapters fit together in the current Textree alpha.

Architecture

The public site and the application runtime are deliberately split.

Public surface

Astro owns:

  • landing pages
  • docs
  • blog
  • SEO metadata, RSS, and sitemap output

Application surface

Phoenix owns:

  • login and authenticated UX
  • /api/v1/*
  • signed provider webhooks
  • /mcp/*

Core state

Neon-backed Postgres is the system of record for:

  • Phoenix-native users and Textree auth identities
  • users and workspaces
  • legacy consent/contact metadata
  • workspace and campaign suppressions
  • messages
  • ledger entries and spend limits
  • provider events
  • funding sessions
  • MCP execution audits

Worker ownership

Oban owns side effects and retries.

  • outbound messages are queued before provider execution
  • provider events are stored before reconciliation
  • replay and retry paths stay out of controllers and LiveViews

Execution rules

Outbound messaging follows a strict path:

  1. workspace suppression check
  2. spend reservation and ledger write
  3. Oban enqueue
  4. provider execution in a worker

That keeps external side effects out of controllers and LiveViews.

Webhook rules

Provider webhooks follow a parallel boundary:

  1. signature verification
  2. normalized event persistence
  3. duplicate detection
  4. Oban enqueue
  5. reconciliation into message, suppression, or funding state

MCP rules

The MCP surface is intentionally narrow in alpha:

  1. Textree bearer-token authentication
  2. route-level scope enforcement
  3. server-registry and allowlist checks
  4. quota and timeout controls
  5. persisted execution audit records

Provider boundaries

Controllers and LiveViews do not call vendors directly.

  • messaging routes talk to the messaging context
  • funding routes talk to the funding context
  • provider-specific HTTP semantics stay inside provider adapters
  • webhook normalization happens before business-state reconciliation

Alpha constraints

This architecture is already usable, but still intentionally incomplete:

  • repo-local ADRs capture the current implementation baseline while the canonical canvas import is still pending
  • some product surfaces are operator-only rather than public API contracts
  • MCP tooling is server-configured, not tenant-configured
  • docs describe the implemented alpha contract, not future roadmap promises