mirror of
https://github.com/wu736139669/hapi.git
synced 2026-08-05 06:24:37 +00:00
weishu
6829ca35a4
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.
272 lines
20 KiB
Markdown
272 lines
20 KiB
Markdown
# 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.
|