OrangeCat

Your AI economic agent — and the platform where it operates.

The Problem

Economic participation still requires gatekeepers. To sell, fund, lend, invest, or govern collectively, you need banks, payment processors, platforms that take cuts and dictate terms. Pseudonymous participation is impossible. AI agents can't transact on your behalf.

The Solution

OrangeCat is an AI-native platform for universal economic participation. Every user gets "My Cat" — an AI agent that manages their economic activity across the full spectrum: exchanging, funding, lending, investing, and governing.

• Any identity: Human, pseudonymous, or AI — all are first-class economic participants
• Bitcoin now, broader rails later: Lightning and on-chain Bitcoin are the only live settlement rails. Fiat and privacy rails remain roadmap work because they do not provide the same shared public audit trail.
• Full economic spectrum: From gifts (no strings) to loans (some strings) to investments (more strings)
• Private where needed, transparent where chosen: E2E encrypted messaging, on-chain transparency when appropriate

What Works Today

• Commerce: Products and services with Bitcoin Lightning payments
• Funding: Account-free Bitcoin support for public projects and other supportable entities
• Lending: Peer-to-peer loans with repayment tracking
• Assets: Real estate, collateral, and rentable asset management
• Groups: Organizations with shared wallets, governance proposals, and collective decision-making
• AI Assistants: Autonomous economic actors as first-class entities
• Events: Time-bound coordination with ticketing
• Documents: Structured context for the AI agent
• Cross-product customers: Live example of FleetCrown (production) as customer of OrangeCat (economic), using typed stakeholder edges + shared wallets + profiles as projects.

Live at orangecat.ch. FleetCrown is a live "customer" of OrangeCat (see projects "OrangeCat" and "FleetCrown" under Mao Nakamoto). Shared BTC wallet. The stakeholder_relationships feature (8 kinds incl. customer) was made production-ready here for this use case — works for all.

Architecture

13 entity types, one registry. One ownership model (actors), one permission layer (database RLS). Adding a new entity type requires 2-3 files.

Technical details

Entity Registry Pattern

src/config/entity-registry.ts — single source of truth for all 13 entity types. Drives CRUD, navigation, forms, and validation. No entity-specific switch statements.

Actor System

Users and groups both have actors. All entities reference actor_id. One ownership model, one permission check — works for individuals, organizations, and (future) AI agents.

Middleware Composition

export default compose(withAuth(), withRateLimit('write'), withValidation(schema))(handler);

Functional composition replaces inheritance. Each middleware does one thing.

Security

• Row Level Security (RLS) at the database level — bugs in app code can't bypass authorization
• Zod schemas as SSOT — TypeScript types derived from schemas, never separate
• Structured API responses across all 40+ routes

Tech Stack

Layer	Technology
Framework	Next.js 15, React 18, TypeScript 5.8
Styling	Tailwind CSS, shadcn/ui
Database	Self-hosted Supabase (PostgreSQL + Auth + RLS) on Hetzner
Bitcoin	Lightning Network, LNURL, bitcoinjs-lib
Auth	Supabase Auth, JWT, Row Level Security
Deployment	Self-hosted on Hetzner (bitbaum, behind Caddy); GitHub Actions CI (gate only, no deploy)

Quick Start

Prerequisites

• Node.js 20+
• A Supabase project (remote — no local Docker needed)

Setup

git clone https://github.com/bitbaum/orangecat.git
cd orangecat
npm install
cp .env.example .env.local
# Fill in Supabase credentials
npm run dev

Dev server starts at http://localhost:3000.

Environment Variables

See .env.example for the full list. Key variables:

• NEXT_PUBLIC_SUPABASE_URL — Supabase project URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY — Supabase anonymous key
• SUPABASE_SERVICE_ROLE_KEY — Server-side Supabase key

Project Structure

src/
  config/entity-registry.ts  -- SSOT: all 13 entity types
  lib/api/                    -- Middleware composition, generic CRUD
  domain/                     -- Business logic (no HTTP, no UI)
  services/                   -- Currency, search, notifications, groups
  features/                   -- Messaging, auth
  app/api/                    -- API routes (thin, composed from middleware)
  components/                 -- UI components (shadcn/ui based)

Testing

17 test suites, 74 tests. Pre-push hooks run type-check, lint, and the full test suite before any code reaches the remote.

Security

See SECURITY.md for reporting vulnerabilities.

License

Proprietary. All Rights Reserved. See LICENSE.