From 6829ca35a44adf1ad824590c3ed91f4b7970bc38 Mon Sep 17 00:00:00 2001 From: weishu Date: Thu, 25 Dec 2025 14:01:13 +0800 Subject: [PATCH] docs: add architectural comparison with Happy and update README Add comprehensive WHY_NOT_HAPPY.md documenting the architectural differences between HAPI's local-first design and Happy's cloud-first approach. Update README with clearer project description and link to new documentation. --- README.md | 5 +- docs/WHY_NOT_HAPPY.md | 271 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 275 insertions(+), 1 deletion(-) create mode 100644 docs/WHY_NOT_HAPPY.md diff --git a/README.md b/README.md index 1a172cbf..a08034f0 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ # hapi -HAPI means "哈皮," a Chinese transliteration of [happy](https://github.com/slopus/happy), great credit to the original Happy project. +HAPI means "哈皮," a Chinese transliteration of [Happy](https://github.com/anthropics/anthropic-cookbook/tree/main/misc/happy). Great credit to the original project. Run Claude Code / Codex / Gemini sessions locally and control them remotely through a Web / PWA / Telegram Mini App. +> **Why HAPI?** HAPI is a local-first alternative to Happy. See [Why Not Happy?](docs/WHY_NOT_HAPPY.md) for the key differences. + ## Features - Start AI coding sessions from any machine. @@ -118,6 +120,7 @@ bun run build:single-exe ## Docs +- `docs/WHY_NOT_HAPPY.md` - Why HAPI exists: architectural differences from Happy - `cli/README.md` - CLI usage and config - `server/README.md` - Server setup and architecture - `web/README.md` - Web app behavior and dev workflow diff --git a/docs/WHY_NOT_HAPPY.md b/docs/WHY_NOT_HAPPY.md new file mode 100644 index 00000000..ce992020 --- /dev/null +++ b/docs/WHY_NOT_HAPPY.md @@ -0,0 +1,271 @@ +# Why Not Happy? + +[Happy](https://github.com/anthropics/anthropic-cookbook/tree/main/misc/happy) is an excellent project. So why build HAPI? + +**The short answer**: Happy is designed for cloud hosting with multiple users. HAPI is designed for self-hosting with a single user. These different goals lead to fundamentally different architectures. + +Happy's cloud-first design requires: +- End-to-end encryption (because you don't trust the server) +- Distributed database + cache + storage (because you need to scale) +- Complex deployment (Docker, multiple services, config files) + +HAPI's local-first design simplifies everything: +- No E2EE needed (your data never leaves your machine) +- Single embedded database (no scaling required) +- One-command deployment (single binary, zero config) + +**TL;DR**: If you want to self-host for personal use, HAPI removes all the complexity that Happy needs for its cloud service. + +--- + +## 1. Architecture Overview + +### Happy: Cloud-First + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ PUBLIC INTERNET │ +│ │ +│ │ +│ ┌─────────────┐ ┌─────────────────────────────────┐ │ +│ │ │ │ │ │ +│ │ Mobile App │◄─────── E2EE ───────►│ Cloud Server │ │ +│ │ │ │ │ │ +│ └─────────────┘ │ ┌───────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ Encrypted Database │ │ │ +│ │ │ (server cannot read) │ │ │ +│ │ │ │ │ │ +│ │ └───────────────────────────┘ │ │ +│ │ │ │ +│ └────────────────┬────────────────┘ │ +│ │ │ +│ │ E2EE │ +│ │ │ +└────────────────────────────────────────────────────────────┼─────────────────────┘ + │ +┌────────────────────────────────────────────────────────────┼─────────────────────┐ +│ PRIVATE NETWORK │ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ CLI │ │ +│ │ │ │ +│ │ ┌────────────────────────────────────┐ │ │ +│ │ │ Encryption Keys │ │ │ +│ │ │ (only client holds the keys) │ │ │ +│ │ └────────────────────────────────────┘ │ │ +│ │ │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────────────────────┘ + + +Data Flow: +┌──────────────────────────────────────────────────────────────────────────────────┐ +│ │ +│ CLI ◄───────► Cloud Server ◄───────► App │ +│ │ │ │ │ +│ │ (encrypt) │ (ciphertext) │ (decrypt) │ +│ ▼ ▼ ▼ │ +│ Keys ──────► [Encrypted Data] ◄────── Keys │ +│ │ │ +│ ▼ │ +│ Server stores │ +│ encrypted blobs │ +│ (zero knowledge) │ +│ │ +└──────────────────────────────────────────────────────────────────────────────────┘ +``` + +### HAPI: Local-First + +``` +┌──────────────────────────────────────────────────────────────────────────────────┐ +│ PRIVATE NETWORK │ +│ │ +│ ┌────────────────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ Single Process / Binary │ │ +│ │ │ │ +│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ CLI │◄──►│ Server │◄──►│ Web App │ │ │ +│ │ │ │ │ │ │ (embedded) │ │ │ +│ │ └──────────────┘ └──────┬───────┘ └──────────────┘ │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ ┌────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ Local Database│ │ │ +│ │ │ (plaintext) │ │ │ +│ │ │ │ │ │ +│ │ └────────────────┘ │ │ +│ │ │ │ +│ └────────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ localhost │ +└────────────────────────────────────────┼─────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────────┐ +│ TUNNEL (Optional) │ +│ │ +│ localhost ────────► public URL (TLS) │ +│ │ +└────────────────────────────────────────┬────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────────┐ +│ PUBLIC INTERNET │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ │ │ +│ │ Remote Clients │ │ +│ │ (PWA / Mini App) │ │ +│ │ │ │ +│ └───────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ + + +Data Flow: +┌──────────────────────────────────────────────────────────────────────────────────┐ +│ │ +│ CLI ◄────────► Server ◄────────► App │ +│ │ │ +│ │ (same machine / process) │ +│ ▼ │ +│ Local Database │ +│ (data never leaves) │ +│ │ │ +│ ▼ │ +│ Tunnel provides │ +│ external access │ +│ (TLS encryption) │ +│ │ +└──────────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. Key Architectural Differences + +### 2.1 Data Location + +| Aspect | Happy | HAPI | +|--------|-------|------| +| **Where data lives** | Cloud server | Your local machine | +| **Who can access** | Server stores encrypted blobs (cannot read) | Only you (data never uploaded) | +| **Trust model** | Don't trust server → need E2EE | Trust local environment → TLS sufficient | + +### 2.2 Deployment Model + +``` +Happy: +┌─────────────────────────────────────────────────────────────────────┐ +│ │ +│ Distributed Services (4+ components) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Database │ │ Cache │ │ Storage │ │ Server │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +│ Requires: Container orchestration, multiple config files │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ + +HAPI: +┌─────────────────────────────────────────────────────────────────────┐ +│ │ +│ Single Binary (everything bundled) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ CLI + Server + Web App + Database (embedded) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ Requires: One command to run │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### 2.3 Security Approach + +| Aspect | Happy | HAPI | +|--------|-------|------| +| **Problem to solve** | Data on untrusted server | External access to local data | +| **Solution** | End-to-end encryption | Tunnel with TLS | +| **Complexity** | High (key management, crypto) | Low (tunnel setup) | +| **Data at rest** | Encrypted | Plaintext (protected by OS) | + +--- + +## 3. Why Different Architectures? + +### Happy's Constraints + +``` +Goal: Multi-user cloud platform + │ + ├──► Users don't trust your server + │ │ + │ └──► Must encrypt everything (E2EE) + │ + ├──► Many concurrent users + │ │ + │ └──► Must scale horizontally (distributed DB + cache) + │ + └──► Multiple devices per user + │ + └──► Must sync state across devices (complex sync logic) + +Result: Sophisticated but complex architecture +``` + +### HAPI's Simplifications + +``` +Goal: Single-user self-hosted tool + │ + ├──► Data stays on your machine + │ │ + │ └──► No E2EE needed (you trust yourself) + │ + ├──► Only one user + │ │ + │ └──► No scaling needed (simple embedded database) + │ + └──► One primary device + │ + └──► Minimal sync logic (tunnel for remote access) + +Result: Simple and portable architecture +``` + +--- + +## 4. Summary + +| Dimension | Happy | HAPI | +|-----------|-------|------| +| **Philosophy** | Cloud-first | Local-first | +| **Data location** | Server (encrypted) | Local (plaintext) | +| **Deployment** | Multiple services | Single binary | +| **Scaling** | Horizontal | None needed | +| **Encryption** | Application-layer E2EE | Transport-layer TLS | +| **Target user** | Teams, cloud users | Individuals, self-hosters | + +--- + +## 5. Conclusion + +The architectural differences stem from fundamentally different product goals: + +- **Happy**: Built for multi-user cloud scenarios. Solves the "untrusted server" problem with E2EE, at the cost of deployment complexity. + +- **HAPI**: Built for single-user self-hosted scenarios. Solves the "remote access" problem with tunneling, achieving one-command deployment. + +**Choose Happy if**: You need multi-user collaboration or team sharing. + +**Choose HAPI if**: You want personal use, data sovereignty, and minimal setup.