docs: Expand project documentation with new guides and updates

Author: tembo[bot]

ACKNOWLEDGMENTS.md

@@ -0,0 +1,65 @@
+# Acknowledgments
+
+We would like to thank the following projects, tools, and communities that made Databuddy possible:
+
+## Core Technologies
+
+### Frontend & Framework
+- **[Next.js](https://nextjs.org/)** - The React framework for production
+- **[React](https://reactjs.org/)** - A JavaScript library for building user interfaces
+- **[TypeScript](https://www.typescriptlang.org/)** - Typed JavaScript at scale
+- **[Tailwind CSS](https://tailwindcss.com/)** - A utility-first CSS framework
+
+### Build & Development
+- **[Turborepo](https://turbo.build/repo)** - High-performance build system for monorepos
+- **[Bun](https://bun.sh/)** - Fast all-in-one JavaScript runtime and toolkit
+- **[Biome](https://biomejs.dev/)** - Fast formatter and linter for JavaScript and TypeScript
+
+### Database & Storage
+- **[PostgreSQL](https://www.postgresql.org/)** - The world's most advanced open source relational database
+- **[ClickHouse](https://clickhouse.com/)** - Fast open-source column-oriented database
+- **[Redis](https://redis.io/)** - In-memory data structure store
+- **[Drizzle ORM](https://orm.drizzle.team/)** - TypeScript ORM
+
+### UI Components & Libraries
+- **[Radix UI](https://www.radix-ui.com/)** - Unstyled, accessible components
+- **[Phosphor Icons](https://phosphoricons.com/)** - Flexible icon family
+- **[Recharts](https://recharts.org/)** - Composable charting library
+- **[TanStack Query](https://tanstack.com/query)** - Powerful data synchronization
+
+### Developer Tools
+- **[Zod](https://zod.dev/)** - TypeScript-first schema validation
+- **[Day.js](https://day.js.org/)** - Fast 2KB alternative to Moment.js
+- **[tRPC](https://trpc.io/)** - End-to-end typesafe APIs
+
+### Testing & Quality
+- **[Vitest](https://vitest.dev/)** - Blazing fast unit test framework
+- **[Playwright](https://playwright.dev/)** - Reliable end-to-end testing
+
+### Infrastructure & Hosting
+- **[Vercel](https://vercel.com/)** - Platform for frontend frameworks and static sites
+- **[Docker](https://www.docker.com/)** - Containerization platform
+
+## Special Thanks
+
+### Open Source Community
+We're grateful to the entire open source community for creating and maintaining the incredible tools and libraries that power Databuddy.
+
+### Contributors
+Thank you to all contributors who have helped improve Databuddy through code, documentation, bug reports, and feedback.
+
+### Privacy-First Analytics Movement
+Inspired by and grateful to privacy-focused analytics projects that are making the web a better place while respecting user privacy.
+
+### Vercel OSS Program
+Special thanks to [Vercel](https://vercel.com/oss) for supporting open source projects through their OSS Program.
+
+## License Acknowledgments
+
+Databuddy is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). All dependencies are used in accordance with their respective licenses.
+
+For a complete list of dependencies and their licenses, see the `package.json` files in each package directory.
+
+---
+
+**Want to be listed here?** We welcome contributions! Check out our [Contributing Guide](CONTRIBUTING.md) to get started.

CONTRIBUTING.md

@@ -128,6 +128,212 @@ Note: Open a pull request to the STAGING branch
 
 ## Code Style
 
-- Use Biome for linting and formatting
-- Follow the coding standards in the README
-- Keep it simple and type-safe
+### Linting and Formatting
+
+- **Use Ultracite** for linting (not ESLint)
+- **Use Prettier** for code formatting
+- **Use Biome** for fast linting and formatting where applicable
+- Run `bun run lint` before committing to ensure code quality
+- Run `bun run format` to auto-format your code
+
+### Coding Standards
+
+Follow the coding standards outlined in the README and `.cursor/rules/`:
+
+**Required Tools & Libraries:**
+- **Bun** - Required for all development (never use npm/pnpm/Node CLI)
+- **Zod v4** - Use `zod/v4` everywhere (not Zod v3)
+- **Phosphor Icons** - Use only Phosphor icons (not Lucide)
+- **Dayjs** - Use for all date handling (never date-fns)
+- **TanStack Query** - Use for data fetching hooks (never SWR)
+
+**Style Guidelines:**
+- **Border Radius**: Use `rounded` (never `rounded-xl` or `rounded-md`)
+- **Type Safety**: Always ensure type-safety and use shared types
+- **Error Handling**: Never throw errors in server actions; use try/catch and return errors
+- **Error Boundaries**: Always use error boundaries properly
+- **Console Usage**: Use appropriate console methods (`console.error`, `console.time`, `console.json`, `console.table`)
+- **useEffect**: Almost never use `useEffect` unless critical
+- **No Placeholders**: Never add placeholders or mock data
+
+See `.cursor/rules/` for the complete enforced ruleset.
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+bun run test
+
+# Run tests in watch mode
+bun run test:watch
+
+# Run tests with coverage
+bun run test:coverage
+
+# Run specific test file
+bun test path/to/test.test.ts
+```
+
+### Writing Tests
+
+**Unit Tests:**
+- Use Vitest for unit testing
+- Place tests next to the code they test (`*.test.ts`)
+- Aim for >80% code coverage
+- Mock external dependencies
+
+**Example unit test:**
+```typescript
+import { describe, it, expect, vi } from 'vitest'
+import { calculateMetrics } from './analytics'
+
+describe('calculateMetrics', () => {
+  it('should calculate basic metrics correctly', () => {
+    const events = [
+      { type: 'pageview', timestamp: Date.now() },
+      { type: 'pageview', timestamp: Date.now() }
+    ]
+
+    const metrics = calculateMetrics(events)
+
+    expect(metrics.pageviews).toBe(2)
+  })
+
+  it('should handle empty events array', () => {
+    const metrics = calculateMetrics([])
+
+    expect(metrics.pageviews).toBe(0)
+  })
+})
+```
+
+**Integration Tests:**
+- Test API endpoints and database operations
+- Use test database and Redis instances
+- Clean up test data after each test
+
+**E2E Tests:**
+- Use Playwright for end-to-end testing
+- Test critical user flows
+- Run in CI/CD pipeline
+
+### Test Coverage Requirements
+
+Maintain test coverage above these thresholds:
+- **Statements**: 80%
+- **Branches**: 75%
+- **Functions**: 80%
+- **Lines**: 80%
+
+## Code Review Process
+
+All contributions go through code review before merging:
+
+1. **Automated Checks**: CI/CD runs tests, linting, and type checking
+2. **CodeRabbit Review**: Automated AI review for common issues
+3. **Manual Review**: Maintainer reviews code for:
+   - Code quality and style adherence
+   - Test coverage
+   - Security considerations
+   - Performance implications
+   - Documentation completeness
+
+### Review Checklist
+
+Before requesting review, ensure:
+- [ ] All tests pass
+- [ ] Code is formatted and linted
+- [ ] Types are correct (no `any` types)
+- [ ] Documentation is updated
+- [ ] Changeset created
+- [ ] Security considerations addressed
+- [ ] Performance impact considered
+- [ ] Error handling implemented
+
+## Architecture Guidelines
+
+### Monorepo Structure
+
+```
+Databuddy/
+├── apps/
+│   ├── web/           # Main dashboard application
+│   ├── docs/          # Documentation site
+│   └── dashboard/     # Analytics dashboard
+├── packages/
+│   ├── sdk/           # Client-side SDK
+│   ├── tracker/       # Event tracking
+│   ├── db/            # Database utilities
+│   ├── validation/    # Shared validation schemas
+│   └── ui/            # Shared UI components
+└── infrastructure/    # Deployment configurations
+```
+
+### Adding New Features
+
+**1. Plan your feature:**
+- Discuss in GitHub Issues first for major features
+- Consider backward compatibility
+- Plan database migrations if needed
+
+**2. Implement incrementally:**
+- Start with types and schemas (Zod v4)
+- Implement core logic with tests
+- Add UI components
+- Update documentation
+
+**3. Database Changes:**
+```bash
+# Make schema changes in packages/db/schema/
+
+# Generate migration
+bun run db:generate
+
+# Apply to local database
+bun run db:push
+
+# Test migration
+bun run db:migrate
+```
+
+**4. Add appropriate tests:**
+- Unit tests for utilities and logic
+- Integration tests for API endpoints
+- E2E tests for user-facing features
+
+### Performance Considerations
+
+- **Database**: Index frequently queried columns
+- **Caching**: Use Redis for expensive queries
+- **Bundle Size**: Keep client bundles small (<200KB)
+- **Batching**: Batch analytics events (use built-in batching)
+- **Images**: Use Next.js Image optimization
+
+## Documentation
+
+### When to Update Docs
+
+Update documentation when:
+- Adding new features
+- Changing APIs or behavior
+- Fixing bugs that affect usage
+- Adding configuration options
+- Changing deployment procedures
+
+### Documentation Files
+
+- **README.md** - Project overview and quick start
+- **CONTRIBUTING.md** - This file
+- **DEPLOYMENT.md** - Deployment and operations
+- **apps/docs/** - User-facing documentation site
+- **Code comments** - Document complex logic
+
+### Writing Good Documentation
+
+- Use clear, concise language
+- Include code examples
+- Add screenshots for UI features
+- Keep it up-to-date
+- Test all examples