Echo

Echo is an open, privacy-minded platform for communities: real-time chat, voice and video (LiveKit), servers and channels, DMs, roles, and the workflows people expect from a modern team or social space—without treating your community as ad inventory.

You can run it yourself (self-host), fork and extend it (AGPL), or use it as the basis for a product you control end-to-end.

From the repository root (Node.js 22.13+, Docker for Postgres):

npm ci
cp .env.example .env
npm run db:up
npm run dev

• API: http://localhost:3000
• Vite dev server: http://localhost:8080

Full setup, PR checks, and maintainer notes: docs/DEVELOPMENT.md.

• What Echo is
• Why Echo
• Open source
• Project structure
• Stack (summary)
• Getting started
• Native apps
• Contributing
• Third-party assets
• License

Echo is a full-stack communication app: a Vue 3 SPA, a Node.js (Fastify) API, Socket.IO for realtime, PostgreSQL for durable data, optional NATS for multi-process scaling, and native Apple clients under clients/apple/ (more platforms to follow). A separate marketing site (Astro) and optional Discord bridge / import tooling exist for migration and interoperability—not as the core identity of the product.

The codebase is organized for operators and contributors: typed shared contracts between client and server, documented API behavior under docs/contracts/, and runbooks under docs/operations/.

• Privacy and consent by design — built around clear boundaries for data, sessions, and what the server is allowed to assume about users.
• You own your deployment — no mandatory third-party control plane; configure auth, storage, voice, and edge the way your threat model requires.
• Realtime-first — chat and presence are first-class; server/voice/video follow a documented LiveKit path with production checklists in-repo.
• Serious engineering guardrails — contract tests, RBAC and snowflake guards in CI, observability hooks, and a single production readiness rollup so progress is inspectable, not hand-wavy.
• Installable where your users are — PWA for the web and native Apple apps in clients/apple/ (iOS first; macOS shared where product-neutral).

Echo is open source under the GNU Affero General Public License v3.0 only (AGPL). Contributions, issues, and pull requests: CONTRIBUTING.md, CODE_OF_CONDUCT.md, .github/SECURITY.md. Documentation index: docs/README.md.

CI (GitHub Actions) — badges target this fork’s default GitHub branch (release/1.0.0). Change ad3lre/echo and branch=… in the URLs if your owner/repo or branch name differs:

Release and signing workflows may need repository secrets on the canonical fork; forks still get format, backend, web, and E2E checks when relevant paths change.

Echo is a single monorepo. UI lives in clients; suites own shared kits and sidecars. Full map: docs/overview/repo-layout.md.

• clients/web/ — Vue 3 + Vite SPA (Pinia, TypeScript). History API navigation (urlNavigation.ts), not vue-router.
• clients/apple/ — Native SwiftUI iOS/macOS clients.
• server/backend/ — Fastify REST API, Socket.IO, Postgres, auth and Echo domain logic.
• contracts/ — Shared TypeScript types/constants (client ↔ server). TS-only — do not commit emitted .js.
• clients/web/src/features/paper/ — Paper editor feature (fold of former top-level paper/).
• server/backend/crypto/ — E2EE + MLS kit (no Vue UI; settings UX stays in clients/web/).
• server/media/ — Media CDN + chat video HLS worker.
• server/voice/ — Voice helper sidecar (LiveKit-adjacent).
• server/activities/ — VC gamespace sidecar + shared game cores.
• server/ops/ — Glue only (scripts/, infra/, server/ops/monitoring/, perf/).
• marketing/ — Astro public site (+ marketing/terms/).
• bot/ — Optional Discord bridge / import tooling.
• docs/ — Narrative docs, plans, and runbooks.

• Install from the repo root (npm ci or npm install). Root install is required (workspaces + devDependencies such as sharp for Twemoji assets). Installing only under clients/web/ is not enough for npm run dev / npm run build.
• Node.js 22.13+ (see package.json engines). For sharp, see sharp install.
• Local stack: npm run db:up then npm run dev (see .env.example). Postgres-like behavior: ECHO_BACKEND_STORAGE=postgres and DATABASE_URL.
• Production-like local bundle: npm run prod (full build + API on :3000 + Vite preview on :4173). Skip rebuild: npm run prod:serve.
• Backend only: npm run build -w backend (or root npm run build) before npm start (node dist/server/backend/src/index.js).
• Production: DATABASE_URL required; /api/v1/mock is not registered in production.
• VPS / bare metal: docs/operations/linux-vps-deployment.md.
• Seed dev data (API running): npm run seed:dev.

The SPA ships a manifest, themed icons under clients/web/public/icons/ (regenerated on npm run build -w web via server/ops/scripts/generate-pwa-icons.mjs), and a minimal service worker (clients/web/public/sw.js). The worker registers in dev and production so Chrome can offer Install Echo on npm run dev (e.g. http://localhost:8080).

• HTTPS: production installability needs a secure context; terminate TLS at your proxy and forward X-Forwarded-Proto when HTTPS enforcement is on (see registerHttpsEnforcementIfConfigured and realtime-scaling).
• Verify: Vite dev or npm run build -w web && npm run preview -w web → Chrome → Install Echo. Hard-reload once if the prompt is missing.
• Icons only: npm run pwa:icons from repo root.

Native clients are first-party apps (not a WebView shell). Start with Apple — see clients/apple/README.md. Passkeys / Universal Links: docs/operations/ios-passkeys.md.

We welcome contributions on GitHub. Start with docs/DEVELOPMENT.md, then CONTRIBUTING.md.

Icons and emoji: marketing/terms/en-US/ATTRIBUTIONS.md.

GNU Affero General Public License v3.0 only — see LICENSE.

If you modify this program and offer it as a network service, the AGPL requires offering Corresponding Source to users of that service under the same license. Distributed binaries must also satisfy source-offer rules. See the GNU AGPL howto and FSF FAQ (AGPL).

Downstream: app stores and notarized bundles may add their own terms; packagers remain responsible for AGPL compliance.