`tpt hearth`

A calm web/PWA social platform for presence, conversation, and human bonds.

tpt hearth is not optimized for growth, productivity, virality, or attention capture. It is a digital lodge: a place to sit, speak gently, and be together without performance pressure.

Come sit. Stay awhile. Just be.

Features

Hearth — intimate persistent chat rooms capped at 12 people
Porch — 20-minute low-friction sessions for meeting new people
Embers — ambient co-presence spaces with optional audio atmosphere
Grove — open room directory searchable by mood and topic
Letters — asynchronous long-form messages with scheduled delivery
Chronicles — private personal archives, exportable as JSON/Markdown
Rituals — optional user-hosted gatherings with gentle summaries
E2E Encryption — private rooms use AES-256-GCM via the Web Crypto API
PWA — installable, offline-capable shell with encrypted draft storage
Real-time presence — native WebSocket server for chat and typing indicators
Admin controls — invite management, moderation, and server settings
Data portability — full JSON/Markdown export and instant account deletion

What this platform rejects

Algorithmic feeds or recommendation engines
Likes, shares, follower counts, and virality metrics
Infinite scrolling and engagement-optimized UI
Ads, tracking pixels, and behavioral analytics
Red notification badges and urgency language

Stack

Layer	Technology
Web framework	Next.js 15 App Router
Language	TypeScript (strict)
Styling	Tailwind CSS
Components	shadcn/ui-style primitives
Database	SQLite (Drizzle ORM), PostgreSQL upgrade path
Real-time	Native WebSockets
Encryption	Web Crypto API (AES-256-GCM, PBKDF2)
PWA	Manifest + Service Worker
Monorepo	pnpm workspaces + Turborepo

Quick start

git clone https://github.com/PhillipC05/tpt-hearth.git
cd tpt-hearth
pnpm install
cp .env.example .env
pnpm dev

Service	URL
Web app	http://localhost:3000
WebSocket server	ws://localhost:4000
SQLite database	`.data/hearth.sqlite`

Environment

Copy the example environment file and edit as needed:

cp .env.example .env

Key variables:

NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_WS_URL=ws://localhost:4000
DATABASE_URL=file:.data/hearth.sqlite
NODE_ENV=development

See .env.example for the full reference.

Scripts

pnpm dev           # Start development server
pnpm build         # Production build
pnpm lint          # Run ESLint
pnpm test          # Unit tests (vitest)
pnpm test:e2e      # End-to-end tests (Playwright)
pnpm db:generate   # Generate Drizzle migrations
pnpm db:migrate    # Run migrations

Documentation

Document	Description
SPEC.md	Full product specification
docs/architecture.md	System design and component overview
docs/database.md	Schema and relationships
docs/encryption.md	E2E encryption design
docs/moderation.md	Moderation workflow
docs/pwa.md	PWA implementation notes
docs/deployment.md	Deployment guide (local, Docker, VPS, Fly.io)
docs/runbook.md	Day-to-day operations runbook

Admin setup

The first admin user must be set directly in the database:

# Using the SQLite CLI
sqlite3 .data/hearth.sqlite \
  "UPDATE users SET is_admin = 1 WHERE handle = 'your-handle';"

From there, admin users can manage invites, moderation, and server settings through the /admin interface.

Contributing

See CONTRIBUTING.md. Read SPEC.md first — contributions must align with the product vision.

License

Apache License 2.0 — see LICENSE.

tpt-hearth

Languages

tpt hearth