# Technology stack reference

Why Trinity uses Elixir, BEAM, Phoenix LiveView, Ecto, Postgres, Oban, PubSub, Fly.io, and Tigris for agent operations.

Status: implemented
Version: latest
Review: source-backed

## Stack thesis

Trinity uses Elixir and Phoenix because autonomous operations are not only a model problem. The product needs long-running workflows, account isolation, live operator control, durable proof, background retries, idempotent external actions, and safe failure behavior. The BEAM stack is a practical match because it treats concurrent processes, supervision, message passing, and fault boundaries as first-class application design tools.

Phoenix is the control plane. Hermes is the hosted runtime. Postgres is the source of truth. Oban is durable orchestration. ToolRouter is the side-effect boundary. LiveView and PubSub make the state visible to operators without pushing credentials or business authority into the browser.

## Technology map

| Technology | Why chosen | Trinity implementation | Official reference |
| --- | --- | --- | --- |
| Elixir and BEAM | Concurrency, supervision, fault-tolerant process design, and predictable runtime behavior | Application supervision, LiveView processes, workers, PubSub, runtime health | [Elixir docs](https://elixir-lang.org/docs.html), [Supervisor](https://hexdocs.pm/elixir/Supervisor.html) |
| Phoenix LiveView | Real-time server-rendered UI with server-owned state | Projects, approvals, status, inbox, CRM, automation, docs, and run timelines | [LiveView](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html) |
| Phoenix contexts | Domain boundaries around accounts, revenue, CRM, Hermes, integrations, approvals, and audit | `Revenue`, `CRM`, `Hermes`, `Integrations`, `Approvals`, `Audit`, `Agency` | [Phoenix contexts](https://phoenix.hexdocs.pm/contexts.html) |
| Ecto | Changesets, constraints, migrations, and explicit schemas | UUID schemas, scoped indexes, check constraints, tenant boundaries, credential-safe metadata | [Ecto](https://hexdocs.pm/ecto/Ecto.html), [Ecto migrations](https://hexdocs.pm/ecto_sql/Ecto.Migration.html) |
| PostgreSQL | Durable relational source of truth for proof, tenancy, idempotency, and financial records | Orders, CRM, run events, ToolCalls, ModelDecisions, approvals, audit, Hermes profiles and skills | [PostgreSQL docs](https://www.postgresql.org/docs/) |
| Oban | Durable job execution, retries, queues, uniqueness, and operational visibility | Hermes runtime jobs, provider checks, fulfillment, sync jobs, retryable work | [Oban](https://hexdocs.pm/oban/Oban.html), [Oban Worker](https://hexdocs.pm/oban/Oban.Worker.html), [unique jobs](https://hexdocs.pm/oban/2.19.2/unique_jobs.html) |
| Phoenix PubSub | Live updates without polling or browser-owned truth | Hermes chat updates, run timeline changes, status updates, notifications | [Phoenix PubSub](https://hexdocs.pm/phoenix_pubsub/Phoenix.PubSub.html) |
| Fly.io | Production deployment, health checks, machines, release/migration flow | `/healthz`, `/readyz`, `/app/bin/migrate`, `/app/bin/server`, Fly deployment docs | [Fly Elixir docs](https://fly.io/docs/elixir/), [Phoenix Fly guide](https://hexdocs.pm/phoenix/fly.html) |
| Tigris or S3-compatible storage | Private objects for documents, attachments, and generated artifacts where configured | Project documents, email attachments, artifacts, preview/download boundaries | [Tigris docs](https://www.tigrisdata.com/docs/), [S3 compatibility](https://www.tigrisdata.com/docs/api/s3/) |

## Why this stack fits autonomous agents

| Agent requirement | Stack answer | Project proof |
| --- | --- | --- |
| Many accounts and projects can run concurrently | BEAM processes and supervised workers handle concurrent sessions and jobs | Account/project-scoped LiveViews, Oban jobs, Hermes profiles |
| Runtime failures should not corrupt business state | Durable state stays in Postgres and Ecto constraints enforce shape | Approval, ToolCall, ModelDecision, and webhook records survive worker failure |
| Operators need live control | LiveView renders server state and receives events without client-side authority | Inline approval cards, runtime posture, CRM, inbox, automation, ledger |
| Side effects must be auditable | ToolRouter centralizes policy, idempotency, adapter calls, and audit events | Every Stripe/Gmail/Hermes/NVIDIA side effect goes through a single boundary or equivalent audited path |
| Agent memory must not leak across tenants | Database-enforced `hermes_skills` scope and project/account `hermes_agent_profiles` | Project-private skills, account promotion, immutable global-core skills |
| Poisoned external content must be contained | Jido-backed content firewall and release-state checks block unreleased raw content | Email/doc/attachment quarantine and metadata-only handoff |
| Money and email need human control | ApprovalRequest/ApprovalEvent and policy gates separate proposal from execution | Gmail sends, spend, provisioning, artifacts, and high-risk actions require approval |

## Design principle for BEAM processes

Trinity uses BEAM processes for runtime resilience and LiveView interactivity, not as the security boundary. Authorization, tenant ownership, idempotency, and proof live in Ecto schemas, Postgres constraints, account membership checks, ToolRouter policies, and approval records.

This matters for Hermes: a project may have its own active chat session and runtime work, but the durable ownership is the project-scoped Hermes profile and the scoped skill records. If a process restarts, the workspace can be recovered from Postgres.

## Deployment posture

Fly starts the release migration command before the web server. Health checks use `/healthz` and readiness uses `/readyz`. Runtime warnings such as Erlang longnames or Tini PID behavior should be documented as operational follow-up when they do not break health checks, but database migrations, secret readiness, and provider gates are deployment-blocking when required by the slice.

## Related pages

- [Architecture](/docs/architecture)
- [Vendor and integration reference](/docs/reference/vendor-map)
- [Provider readiness](/docs/runbooks/provider-readiness)
- [ToolRouter](/docs/concepts/toolrouter)
- [ModelRouter](/docs/concepts/modelrouter)
- [Security And Governance](/docs/security-governance)


Source paths:
- `mix.exs`
- `config/runtime.exs`
- `lib/autonomous_agency/application.ex`
- `lib/autonomous_agency_web/router.ex`
- `lib/autonomous_agency_web/components/layouts.ex`
- `lib/autonomous_agency_web/live/project_live/show.ex`
- `lib/autonomous_agency/tools/tool_router.ex`
- `lib/autonomous_agency/ai/model_router.ex`
- `priv/repo/migrations`
- `docs/FLY_LIVE_DEPLOYMENT.md`
- `docs/plans/2026-06-29-current-production-readiness-plan.md`