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

• 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-analytics/Databuddy.git
cd databuddy

2. Install dependencies:

bun install

3. Set up environment variables:

cp .env.example .env

4. Start Docker services (PostgreSQL, Redis, ClickHouse):

docker-compose up -d

5. Set up the database:

bun db:push

6. Build the SDK:

bun sdk:build

7. Start development servers:

bun run dev

8. Seed the database with sample data (optional):

bun db:seed <WEBSITE_ID> [DOMAIN] [EVENT_COUNT]

Examples:

bun db:seed g0zlgMtBaXzIP1EGY2ieG onlybuddies.com 10000
bun db:seed d7zlgMtBaSzIL1EGR2ieR notmybuddy.cc 5000

Note: You can find your website ID in your website overview settings.

💻 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
• bun run build - Build all applications
• bun run start - Start all applications in production mode
• bun run lint - Lint all code with Ultracite
• bun run format - Format all code with Prettier
• bun run check-types - Type check all TypeScript code
• bun run db:studio - Open Drizzle Studio for database management
• bun run db:generate - Generate Drizzle ORM types
• bun run db:push - Apply database schema changes
• bun run db:migrate - Run database 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 the deployment documentation in our docs.

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.
• Use Ultracite for linting and formatting.
• Use Prettier for code formatting.

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