The open-source, local-first personal finance app.
Important
Papaya is in a pre-alpha state, and only suitable for use by developers
This is the mono-repo source for services used to run Papaya.
Papaya is a modern, local-first personal finance application built with privacy and user control in mind. It leverages CouchDB's robust synchronization capabilities to provide seamless data access across devices while keeping your financial data under your control.
- 🔒 Privacy-First: Your data stays local and syncs only with your chosen CouchDB instance
- 🌐 Local-First Architecture: Works offline, syncs when online
- 📱 Modern UI: Built with React and Material-UI for a sleek, responsive experience
- 🔐 Secure Authentication: JWT-based authentication with CouchDB integration
- 📊 Multi-Device Sync: Seamless synchronization across all your devices
- 🛠️ Developer-Friendly: Open source with a modular architecture
Papaya consists of four main packages:
papaya/
├── packages/
│ ├── papaya-web/ # React frontend application
│ ├── papaya-server/ # Node.js backend API server
│ ├── papaya-docs/ # Next.js documentation site
│ └── papaya-shortcut/ # Quick access landing page
Frontend (papaya-web):
- React 19 with TypeScript
- Material-UI v7 for components
- TanStack Router for routing
- TanStack Query for data fetching
- PouchDB for local data storage
- Zustand for state management
- React Hook Form + Zod for form validation
Backend (papaya-server):
- Node.js with Express
- CouchDB integration via Nano
- JWT authentication
- TypeScript
- CORS and proxy middleware
Database:
- CouchDB with
couch_peruserfeature - Database-per-user architecture
- Built-in replication and sync
- Node.js 18+ and npm
- CouchDB instance (local or remote)
- Docker (optional, for containerized deployment)
-
Clone the repository
git clone https://github.com/your-org/papaya.git cd papaya -
Install dependencies
make install
-
Start CouchDB
# Option 1: Using Docker make docker-dev # Option 2: Local CouchDB instance # Make sure CouchDB is running on localhost:5984
-
Start development servers
# Terminal 1: Start the backend make dev-server # Terminal 2: Start the frontend make dev-client
-
Access the application
- Frontend: http://localhost:5173
- Backend API: http://localhost:3000
- CouchDB Admin: http://localhost:5984/_utils
# Build production image
make docker-build-prod
# Run with Docker Compose
make docker-dev-detached# Build all packages
make build
# Deploy server package
cd packages/papaya-server
npm start- Web App Documentation - Frontend development guide
- Server Documentation - Backend API and configuration
- Documentation Site - User and developer docs
- Quick Access - Landing page service
# Development
make dev-client # Start frontend dev server
make dev-server # Start backend dev server
# Building
make build # Build all packages
make web-build # Build web package only
make build-server # Build server package only
# Docker
make docker-dev # Start development environment
make docker-stop # Stop Docker services
make docker-clean # Clean up Docker resources
# Maintenance
make clean # Clean all build artifacts
make install # Install all dependenciespapaya/
├── packages/
│ ├── papaya-web/ # Frontend React application
│ │ ├── src/ # Source code
│ │ ├── public/ # Static assets
│ │ └── dist/ # Built assets
│ ├── papaya-server/ # Backend Express server
│ │ ├── src/ # Source code
│ │ ├── web-assets/ # Frontend assets for serving
│ │ └── dist/ # Compiled JavaScript
│ ├── papaya-docs/ # Documentation site (Next.js)
│ └── papaya-shortcut/ # Landing page (Next.js)
├── docker/ # Docker configuration
├── Makefile # Build automation
└── README.md # This file
Papaya uses a flexible YAML-based configuration system. See the server documentation for detailed configuration options.