|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Repository Overview |
| 6 | + |
| 7 | +Cube is a semantic layer for building data applications. This is a monorepo containing the complete Cube ecosystem including: |
| 8 | +- Cube backend server and core components |
| 9 | +- Client libraries for JavaScript/React/Vue/Angular |
| 10 | +- Database drivers for various data sources |
| 11 | +- Documentation site |
| 12 | +- Rust components (CubeSQL, CubeStore) |
| 13 | + |
| 14 | +## Development Commands |
| 15 | + |
| 16 | +**Note: This project uses Yarn as the package manager.** |
| 17 | + |
| 18 | +### Core Build Commands |
| 19 | +```bash |
| 20 | +# Build all packages |
| 21 | +yarn build |
| 22 | + |
| 23 | +# Run TypeScript compilation across all packages |
| 24 | +yarn tsc |
| 25 | + |
| 26 | +# Watch mode for TypeScript compilation |
| 27 | +yarn tsc:watch |
| 28 | + |
| 29 | +# Clean build artifacts |
| 30 | +yarn clean |
| 31 | + |
| 32 | +# Run linting across all packages |
| 33 | +yarn lint |
| 34 | + |
| 35 | +# Fix linting issues |
| 36 | +yarn lint:fix |
| 37 | + |
| 38 | +# Lint package.json files |
| 39 | +yarn lint:npm |
| 40 | +``` |
| 41 | + |
| 42 | +### Testing Commands |
| 43 | +```bash |
| 44 | +# Run tests (most packages have individual test commands) |
| 45 | +yarn test |
| 46 | + |
| 47 | +# Test individual packages |
| 48 | +cd packages/cubejs-[package-name] |
| 49 | +yarn test |
| 50 | +``` |
| 51 | + |
| 52 | +### Documentation Development |
| 53 | +The documentation is in `/docs` directory: |
| 54 | +```bash |
| 55 | +cd docs |
| 56 | +yarn dev # Start development server |
| 57 | +yarn build # Build for production |
| 58 | +``` |
| 59 | + |
| 60 | +## Architecture Overview |
| 61 | + |
| 62 | +### Monorepo Structure |
| 63 | +- **`/packages`**: All JavaScript/TypeScript packages managed by Lerna |
| 64 | + - Core packages: `cubejs-server-core`, `cubejs-schema-compiler`, `cubejs-query-orchestrator` |
| 65 | + - Client libraries: `cubejs-client-core`, `cubejs-client-react`, etc. |
| 66 | + - Database drivers: `cubejs-postgres-driver`, `cubejs-bigquery-driver`, etc. |
| 67 | + - API layer: `cubejs-api-gateway` |
| 68 | +- **`/rust`**: Rust components including CubeSQL (SQL interface) and CubeStore (distributed storage) |
| 69 | +- **`/docs`**: Next.js documentation site |
| 70 | +- **`/examples`**: Example implementations and recipes |
| 71 | + |
| 72 | +### Key Components |
| 73 | +1. **Schema Compiler**: Compiles data models into executable queries |
| 74 | +2. **Query Orchestrator**: Manages query execution, caching, and pre-aggregations |
| 75 | +3. **API Gateway**: Provides REST, GraphQL, and SQL APIs |
| 76 | +4. **CubeSQL**: Postgres-compatible SQL interface (Rust) |
| 77 | +5. **CubeStore**: Distributed OLAP storage engine (Rust) |
| 78 | + |
| 79 | +### Package Management |
| 80 | +- Uses Yarn workspaces with Lerna for package management |
| 81 | +- TypeScript compilation is coordinated across packages |
| 82 | +- Jest for unit testing with package-specific configurations |
| 83 | + |
| 84 | +## Testing Approach |
| 85 | + |
| 86 | +### Unit Tests |
| 87 | +- Most packages have Jest-based unit tests in `/test` directories |
| 88 | +- TypeScript packages use `jest.config.js` with TypeScript compilation |
| 89 | +- Snapshot testing for SQL compilation and query planning |
| 90 | + |
| 91 | +### Integration Tests |
| 92 | +- Driver-specific integration tests in `/packages/cubejs-testing-drivers` |
| 93 | +- End-to-end tests in `/packages/cubejs-testing` |
| 94 | +- Docker-based testing environments for database drivers |
| 95 | + |
| 96 | +### Test Commands |
| 97 | +```bash |
| 98 | +# Individual package testing |
| 99 | +cd packages/[package-name] |
| 100 | +yarn test |
| 101 | + |
| 102 | +# Driver integration tests (requires Docker) |
| 103 | +cd packages/cubejs-testing-drivers |
| 104 | +yarn test |
| 105 | +``` |
| 106 | + |
| 107 | +## Development Workflow |
| 108 | + |
| 109 | +1. **Making Changes**: Work in individual packages, changes are coordinated via Lerna |
| 110 | +2. **Building**: Use `yarn tsc` to compile TypeScript across all packages |
| 111 | +3. **Testing**: Run relevant tests for modified packages |
| 112 | +4. **Linting**: Ensure code passes `yarn lint` before committing |
| 113 | + |
| 114 | +## Common File Patterns |
| 115 | + |
| 116 | +- `*.test.ts/js`: Jest unit tests |
| 117 | +- `jest.config.js`: Jest configuration per package |
| 118 | +- `tsconfig.json`: TypeScript configuration (inherits from root) |
| 119 | +- `CHANGELOG.md`: Per-package changelogs maintained by Lerna |
| 120 | +- `src/`: Source code directory |
| 121 | +- `dist/`: Compiled output (not committed) |
| 122 | + |
| 123 | +## Important Notes |
| 124 | + |
| 125 | +- This is documentation for the old Cube docs site structure (the existing `/docs/CLAUDE.md` refers to the documentation site) |
| 126 | +- The main Cube application development happens in `/packages` |
| 127 | +- For data model changes, focus on `cubejs-schema-compiler` package |
| 128 | +- For query execution changes, focus on `cubejs-query-orchestrator` package |
| 129 | +- Database connectivity is handled by individual driver packages |
| 130 | + |
| 131 | +## Key Dependencies |
| 132 | + |
| 133 | +- **Lerna**: Monorepo management and publishing |
| 134 | +- **TypeScript**: Primary language for most packages |
| 135 | +- **Jest**: Testing framework |
| 136 | +- **Rollup**: Bundling for client libraries |
| 137 | +- **Docker**: Testing environments for database drivers |
0 commit comments