README.md

Databuddy

A comprehensive analytics and data management platform built with Next.js, TypeScript, and modern web technologies. Databuddy provides real-time analytics, user tracking, and data visualization capabilities for web applications.

🌟 Features

• 📊 Real-time analytics dashboard
• 👥 User behavior tracking
• 📈 Advanced data visualization // Soon
• 🔒 Secure authentication
• 📱 Responsive design
• 🌐 Multi-tenant support
• 🔄 Real-time updates // Soon
• 📊 Custom metrics // Soon
• 🎯 Goal tracking
• 📈 Conversion analytics
• 🔍 Custom event tracking
• 📊 Funnel analysis
• 📈 Cohort analysis // Soon
• 🔄 A/B testing // Soon
• 📈 Export capabilities // Soon
• 🔒 GDPR compliance
• 🔐 Data encryption
• 📊 API access

📚 Table of Contents

• Project Structure
• Getting Started
• Development
• Contributing
• Security
• FAQ
• Support
• License

🚀 Getting Started

Prerequisites

• Bun
• PostgreSQL
• Redis
• Cloudflare account
• Vercel account

Installation

1. Clone the repository:

git clone https://github.com/databuddy/databuddy.git
cd databuddy

2. Install dependencies (Bun only):

bun install

3. Set up environment variables:

cp apps/dashboard/.env.example apps/dashboard/.env
cp apps/landing/.env.example apps/landing/.env
cp apps/admin/.env.example apps/admin/.env
cp apps/api/.env.example apps/api/.env

4. Start development servers (Bun only):

bun run dev

💻 Development

Available Scripts

Check the root package.json for available scripts. Here are some common ones:

• bun run dev - Start all applications in development mode (if defined)
• bun run db:studio - Open Drizzle Studio for database management
• bun run clickhouse:init - Initialize ClickHouse tables
• bun run db:generate - Generate Drizzle ORM types
• bun run db:push - Apply database migrations
• bun run db:migrate - Generate and run migrations
• bun run db:deploy - Deploy database migrations
• bun run sdk:build - Build the SDK package
• bun run email:dev - Start the email development server

You can also cd into any package and run its scripts directly.

Development Workflow

1. Create a new branch:

git checkout -b feature/your-feature

2. Make your changes

3. Run tests:

bun run test

4. Create a changeset:

bun run changeset

5. Commit your changes:

git add .
git commit -m "feat: your feature"

6. Push your changes:

git push origin feature/your-feature

7. Create a Pull Request

🤝 Contributing

See CONTRIBUTING.md for guidelines.

🔒 Security

See SECURITY.md for reporting vulnerabilities.

❓ FAQ

General

1. What is Databuddy? Databuddy is a comprehensive analytics and data management platform.

2. How do I get started? Follow the Getting Started guide.

3. Is it free? Check our pricing page.

Technical

1. What are the system requirements? See Prerequisites.

2. How do I deploy? See Deployment.

3. How do I contribute? See Contributing.

💬 Support

• Documentation
• Discord
• Twitter
• GitHub Issues
• Email Support

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.

Copyright (c) 2025 Databuddy

🙏 Acknowledgments

See ACKNOWLEDGMENTS.md for credits.

⚠️ Coding Standards & Rules

• Bun is required for all development and scripts. Do not use npm, pnpm, or Node.js CLI for install, run, or dev.
• Zod v4 (from zod/v4) is required everywhere. Do not use Zod v3.
• Use only Phosphor icons (not Lucide).
• Use Dayjs for date handling (never date-fns).
• Use Tanstack Query for hooks (never SWR).
• Use rounded for border radius (never rounded-xl or rounded-md).
• Never add placeholders or mock data.
• Always ensure type-safety and use shared types where possible.
• Never throw errors in server actions; use try/catch and return errors to the client.
• Always use error boundaries properly.
• Console usage: Use console.error, console.time, console.json, console.table, etc. appropriately.
• Almost never use useEffect unless critical.

See .cursor/rules/ for the full enforced ruleset.