buster/README.md

# Buster

A modern data analytics platform that enables teams to interact with their data through AI-powered conversations, beautiful dashboards, and automated insights.

## Quick Start

### Prerequisites
- Node.js 20+
- pnpm 9+
- PostgreSQL (via Supabase local or cloud)

### Setup

1. **Clone the repository**
```bash
git clone https://github.com/buster-so/buster.git
cd buster
```

2. **Install dependencies**
```bash
pnpm install
```

3. **Set up environment variables**
```bash
cp .env.example .env
# Edit .env with your configuration
```

4. **Start development servers**
```bash
turbo dev
```

The application will be available at:
- Web app: http://localhost:3000
- API server: http://localhost:8080

## Architecture Overview

Buster follows a modular monorepo architecture where:
- **Packages** are standalone building blocks containing reusable logic and types
- **Apps** assemble packages to create user-facing applications

### Apps

| App | Description | Stack |
|-----|-------------|-------|
| `@buster-app/web` | Main web application | TanStack Start, React |
| `@buster-app/server` | API server | Node.js, Hono |
| `@buster-app/trigger` | Background job processor | Trigger.dev v3 |
| `@buster-app/cli` | Command-line interface | TypeScript, Bun |
| `@buster-app/electric-server` | Real-time sync server | Electric SQL |
| `@buster-app/api` | Legacy API (being migrated) | Rust (deprecated) |

### Core Packages

| Package | Purpose |
|---------|---------|
| `@buster/database` | Database schema, migrations, and ALL query logic (Drizzle ORM) |
| `@buster/server-shared` | API contracts, request/response types |
| `@buster/data-source` | Customer database connectors (PostgreSQL, MySQL, BigQuery, Snowflake) |
| `@buster/ai` | AI agents and workflows (AI SDK v5) |
| `@buster/access-controls` | Permission and security logic |

## Development

### Commands

All development commands use Turbo for optimal caching and parallelization:

```bash
# Building
turbo build                          # Build entire monorepo
turbo build --filter=@buster/ai      # Build specific package

# Linting
turbo lint                           # Lint entire monorepo
turbo lint --filter=@buster-app/web  # Lint specific app

# Testing
turbo test:unit                      # Run all unit tests
turbo test:unit --filter=@buster/database  # Test specific package

# Development
turbo dev                            # Start all dev servers
turbo dev --filter=@buster-app/web   # Start specific app
```

### Development Workflow

1. **Write tests first** - Follow test-driven development
2. **Check types** - Run `turbo build` to ensure type safety
3. **Lint code** - Run `turbo lint` to maintain code quality
4. **Run tests** - Run `turbo test:unit` before committing

### Testing

Tests are colocated with source files:
- `file.test.ts` - Unit tests
- `file.int.test.ts` - Integration tests

```bash
turbo test:unit        # Fast, isolated unit tests
turbo test:integration # Tests with external dependencies
```

### Database

For local development with Supabase:
```bash
# Start Supabase locally
npx supabase start

# Run migrations
turbo db:migrate

# Access database
psql "postgresql://postgres:postgres@127.0.0.1:54322/postgres"
```

## Contributing

### Code Style

We follow functional programming principles:
- Pure functions over classes
- Immutable data structures
- Type-safe with Zod schemas
- Modular, composable code

### Pull Request Process

1. Create a feature branch
2. Write tests for new functionality
3. Ensure `turbo build lint test:unit` passes
4. Submit PR with clear description
5. Address review feedback

### Documentation

- Each package/app has its own README.md
- CLAUDE.md files provide AI assistant guidance
- Keep documentation close to code

## Project Structure

```
buster/
├── apps/                 # User-facing applications
│   ├── web/             # Main web application
│   ├── server/          # API server
│   ├── trigger/         # Background jobs
│   └── cli/             # Command-line tools
├── packages/            # Reusable modules
│   ├── database/        # Database layer
│   ├── server-shared/   # API contracts
│   ├── data-source/     # Data connectors
│   └── ai/              # AI capabilities
├── turbo.json           # Turbo configuration
├── package.json         # Root package.json
└── .env.example         # Environment template
```

## Tech Stack

- **Frontend**: React, TanStack Start, TailwindCSS
- **Backend**: Node.js, Hono, TypeScript
- **Database**: PostgreSQL (Supabase), Drizzle ORM
- **AI**: OpenAI, Anthropic, AI SDK v5
- **Background Jobs**: Trigger.dev v3
- **Testing**: Vitest
- **Build**: Turborepo, pnpm

## Migration Notice

**Note**: The Rust API (`apps/api`) is legacy code being migrated to TypeScript. All new development should use the TypeScript stack in `apps/server`.

## License

[License information]

## Support

[Support channels and documentation links]