鲲侯·Karma

The Ledger of Destiny. / 掌控财富命运的记账系统。

English | 简体中文

---

Important

🔴 Live Demo: https://karma.xuebz.com/

Experience the "Guest Demo" mode with pre-populated data (2024-2026). No signup required. Just click "👋 Guest Demo" on the login page. Note: Guest data is stored locally in your browser memory and resets on refresh. It does not touch the real database.

📖 Introduction (简介)

Kunhou Karma is not just a bookkeeping tool; it is a "Personal Micro-SaaS Financial System" designed for the modern era.

Most finance apps are either too simple (manual input only) or too complex (requiring Docker/Servers). Karma strikes the perfect balance by leveraging a Serverless + Edge architecture. It delivers enterprise-grade security, infinite scalability, and zero maintenance cost for individual users.

鲲侯·Karma 不仅仅是一个记账工具，它是一套现代化的 "个人微型金融 SaaS 系统"。 大多数记账软件要么太简单（只是个 Excel），要么太重（需要自己维护服务器 docker）。Karma 通过 Serverless + Edge 架构实现了完美的平衡：企业级的安全与高可用，同时保持零运维成本。

🌟 Why Karma? (核心亮点)

1. Zero Maintenance Architecture (零运维架构)

Karma runs entirely on the Edge. No servers to patch. No disks to fill up.

• Compute: Vercel Edge Functions (Global CDN Distribution)
• Database: Supabase (PostgreSQL with RLS Security)
• Assets: Cloudflare R2 (AWS S3 Compatible, Zero Egress Fees)

2. The Cleaning Algorithm (清洁算法) ✨

We take "Data Ownership" seriously. Deleting an account isn't just a flag update.

• Physical Destruction: When you delete a transaction or account, Karma recursively calls Cloudflare R2 to physically destroy every attached receipt image.
• No Residuals: We ensure no "Orphan Data" is ever left behind in your storage buckets.

3. Advanced Security & Isolation (分布式风控) 🛡️

• Dual-Factor Zombie Check: Your account activity is tracked via a distributed "Heartbeat" system. Even if you don't login to the main dashboard, your activity in Karma sends survival signals to prevent your account from being flagged as inactive. (Karma ↔ Sub-App Heartbeat Sync).
• Scope Lockdown: We distinguish between Local Logout (clear current session) and Global Logout (destroy all sessions), preventing accidental cross-app session termination.

4. Decoupled Authorization (权限解耦) 🔐

Karma operates on a strictly isolated authorization table (karma_authorized_users). Your status in Karma is completely independent of other apps in the ecosystem (like user matrix), ensuring true multi-tenant isolation even within a shared database architecture.

⚡ Functional Features (功能特性)

• Multi-Currency Engine: Supports CNY, USD, EUR, GBP, JPY, HKD, AUD, MYR, THB, SGD with auto-updating exchange rates.
• 50-Year Visualization: Dashboard supports a timeline from 2020 to 2070.
• Permission Slot System: A reimagined, 10-slot dedicated attachment interface for power users.
• Admin God View: Built-in specialized administration panel for user management.

🛠️ Tech Stack (技术栈)

This project is a textbook example of the "Golden Triangle" stack:

• Frontend: Vue 3.5 (Composition API), Vite 8 (Rolldown), TailwindCSS v4
• Language: TypeScript 5.9 (Strict Mode)
• Routing: Vue Router 5
• Backend: Supabase (PostgreSQL, Auth, Edge Functions)
• Storage: Cloudflare R2 (S3 Protocol)
• Deployment: Vercel

🚀 Getting Started

1. Clone the repository

   git clone https://github.com/perfhelf/Karma.git
   cd Karma

2. Install dependencies

   npm install

3. Configure Environment Create a .env file in the root directory:

   VITE_SUPABASE_URL=your_supabase_url
   VITE_SUPABASE_ANON_KEY=your_supabase_key
   ADMIN_EMAIL=your_admin_email
   R2_ACCOUNT_ID=your_r2_id
   R2_ACCESS_KEY_ID=your_r2_key
   R2_SECRET_ACCESS_KEY=your_r2_secret
   R2_BUCKET_NAME=your_bucket_name
   R2_PUBLIC_DOMAIN=your_r2_domain

4. Run Development Server

   npm run dev

📄 License

This project is open-sourced under the MIT License.

---

Built with ❤️ by perfhelf (Xuebz Design)