Documentation

Getting started

Run the Astro site and Phoenix control plane locally, then walk the current alpha workflow.

Getting started

Textree is split into two apps:

  • apps/site for the public Astro site
  • apps/web for the Phoenix app, developer API, webhooks, and MCP endpoints

Local workflow

  1. Install Node 22+, Elixir 1.19+, Erlang/OTP 28+, and PostgreSQL.
  2. Copy apps/web/.env.example to apps/web/.env.local.
  3. Copy apps/site/.env.example to apps/site/.env.local.
  4. Generate a Proton SMTP Submission token before sending real local email.
  5. Run pnpm setup from the repo root.
  6. Start Astro with pnpm --dir apps/site dev.
  7. Start Phoenix with cd apps/web && mix phx.server.

Local URLs

  • Astro public site: http://localhost:4321
  • Phoenix app and API: http://localhost:4001

Environment groups

Environment variables are scoped by responsibility:

  • Phoenix local runtime: apps/web/.env.local
  • Astro local public config: apps/site/.env.local
  • production deploy/admin operations: devops/env/prod.env.local
  • test deploy/admin operations: devops/env/test.env.local

Do not use root env files. Only scoped example files are committed.

First-run alpha workflow

Once the stack is up:

  1. Sign up or log in through Textree at /signup or /login.
  2. Open /app.
  3. Use a Textree access token with messages:write for API calls.
  4. Confirm the recipient is not under a workspace suppression.
  5. Set a spend limit.
  6. Optionally create a funding session for Peer-backed balance visibility.
  7. Use the Textree bearer token against POST /api/v1/messages.
  8. Poll GET /api/v1/messages/:id or inspect /app for provider and funding state.

Verification commands

  • pnpm test
  • pnpm verify
  • pnpm app:test
  • pnpm www:check
  • pnpm www:build

What the current alpha guarantees

  • stable route namespaces
  • Neon-ready Ecto config
  • Oban queues for messaging and webhook work
  • Phoenix-native auth and local identity normalization
  • workspace and campaign suppression enforcement
  • provider STOP/opt-out reconciliation into workspace suppressions
  • spend authorization before provider execution
  • verified messaging and funding webhook ingestion
  • MCP execution audits, quotas, and timeout policy

What is not public yet

The current alpha still keeps some critical setup inside the authenticated app rather than public API endpoints:

  • workspace/campaign suppression management
  • spend-limit management
  • funding-session creation