|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +SwiftDataTransferObjects is a Swift Package Manager library containing Data Transfer Objects (DTOs) used by the TelemetryDeck Server. The project started out as a way for various projects to share code, but now it is mainly used to develop Swift struct representations of Apache Druid data structures and query generation. Most other code is mostly unused. The main consumer of this library is a Swift Vapor server application that handles telemetry data processing and analytics. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +### Building and Testing |
| 12 | +```bash |
| 13 | +# Build the project |
| 14 | +swift build |
| 15 | + |
| 16 | +# Run all tests |
| 17 | +swift test |
| 18 | + |
| 19 | +# Run specific test target |
| 20 | +swift test --filter DataTransferObjectsTests |
| 21 | +swift test --filter QueryTests |
| 22 | +swift test --filter QueryResultTests |
| 23 | +swift test --filter QueryGenerationTests |
| 24 | +swift test --filter SupervisorTests |
| 25 | +swift test --filter DataSchemaTests |
| 26 | + |
| 27 | +# Build in release mode |
| 28 | +swift build -c release |
| 29 | +``` |
| 30 | + |
| 31 | +### Package Management |
| 32 | +```bash |
| 33 | +# Clean build artifacts |
| 34 | +swift package clean |
| 35 | + |
| 36 | +# Update dependencies |
| 37 | +swift package update |
| 38 | + |
| 39 | +# Generate Xcode project (optional) |
| 40 | +swift package generate-xcodeproj |
| 41 | +``` |
| 42 | + |
| 43 | +## Architecture Overview |
| 44 | + |
| 45 | +### Core Data Models |
| 46 | +- **DTOv1/DTOv2**: Main data transfer objects with versioning |
| 47 | + - `DTOv1`: Legacy models (InsightGroup, LexiconPayloadKey, OrganizationJoinRequest) |
| 48 | + - `DTOv2`: Current models (Organization, User, App, Insight, Badge, etc.) |
| 49 | +- **Models.swift**: Additional DTOs for API requests, authentication, and UI state |
| 50 | + |
| 51 | +### Query System |
| 52 | +- **CustomQuery**: Main query builder for Apache Druid integration |
| 53 | + - Supports multiple query types: timeseries, groupBy, topN, scan, timeBoundary, funnel, experiment |
| 54 | + - Handles filters, aggregations, post-aggregations, and time intervals |
| 55 | +- **Query Components**: |
| 56 | + - `Aggregator`: Define aggregation functions (sum, count, etc.) |
| 57 | + - `Filter`: Query filtering logic |
| 58 | + - `DimensionSpec`: Dimension specifications for grouping |
| 59 | + - `QueryGranularity`: Time granularity (day, week, month) |
| 60 | + - `VirtualColumn`: Computed columns |
| 61 | + |
| 62 | +### Druid Integration |
| 63 | +- **Druid/**: Complete Apache Druid configuration DTOs |
| 64 | + - `configuration/`: Tuning configs, compaction configs |
| 65 | + - `data/input/`: Input formats, sources, and dimension specs |
| 66 | + - `indexing/`: Parallel indexing, batch processing |
| 67 | + - `ingestion/`: Native batch ingestion specs |
| 68 | + - `segment/`: Data schema and transformation specs |
| 69 | + - `Supervisor/`: Kafka streaming supervision |
| 70 | + |
| 71 | +### Chart Configuration |
| 72 | +- **ChartConfiguration**: Display settings for analytics charts |
| 73 | +- **ChartDefinitionDTO**: Chart metadata and configuration |
| 74 | +- **InsightDisplayMode**: Chart types (lineChart, barChart, pieChart, etc.) |
| 75 | + |
| 76 | +### Query Results |
| 77 | +- **QueryResult**: Polymorphic result handling for different query types |
| 78 | +- **TimeSeriesQueryResult**: Time-based query results |
| 79 | +- **TopNQueryResult**: Top-N dimension results |
| 80 | +- **GroupByQueryResult**: Grouped aggregation results |
| 81 | +- **ScanQueryResult**: Raw data scanning results |
| 82 | + |
| 83 | +## Key Dependencies |
| 84 | + |
| 85 | +- **SwiftDateOperations**: Date manipulation utilities |
| 86 | +- **Apple Swift Crypto**: Cryptographic hashing for query stability |
| 87 | + |
| 88 | +## Development Notes |
| 89 | + |
| 90 | +### DTO Versioning |
| 91 | +The library uses a versioning strategy with `DTOv1` and `DTOv2` namespaces. `DTOv2.Insight` is deprecated in favor of V3InsightsController patterns. |
| 92 | + |
| 93 | +### Query Hashing |
| 94 | +CustomQuery implements stable hashing using SHA256 for caching and query deduplication. The `stableHashValue` property provides consistent query identification. |
| 95 | + |
| 96 | +### Test Structure |
| 97 | +Tests are organized by functionality: |
| 98 | +- **DataTransferObjectsTests**: Basic DTO serialization/deserialization |
| 99 | +- **QueryTests**: Query building and validation |
| 100 | +- **QueryResultTests**: Result parsing and handling |
| 101 | +- **QueryGenerationTests**: Advanced query generation (funnels, experiments) |
| 102 | +- **SupervisorTests**: Druid supervisor configuration |
| 103 | +- **DataSchemaTests**: Data ingestion schema validation |
| 104 | + |
| 105 | +### Encoding/Decoding |
| 106 | +The library uses custom JSON encoding/decoding with: |
| 107 | +- `JSONEncoder.telemetryEncoder`: Consistent date formatting |
| 108 | +- Custom wrappers (`StringWrapper`, `DoubleWrapper`) for flexible JSON parsing |
| 109 | +- `DoublePlusInfinity`: Handles infinity values in query results |
0 commit comments