|
| 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 | +TerriaMap is a complete geospatial catalog explorer website built using the TerriaJS library. This is a customizable starting point for building interactive 3D/2D web-based mapping applications. The application uses Cesium for 3D globe visualization and falls back to Leaflet for 2D mapping. |
| 8 | + |
| 9 | +## Workspace Structure |
| 10 | + |
| 11 | +This is a **Yarn workspace monorepo** with packages defined in the root package.json: |
| 12 | + |
| 13 | +- `packages/terriajs/` - The core TerriaJS library (local package) |
| 14 | +- `packages/cesium/` - Cesium library |
| 15 | +- `packages/terriajs-server/` - Node.js server for proxying |
| 16 | +- `packages/plugin-sample/` - Example plugin |
| 17 | + |
| 18 | +## Development Commands |
| 19 | + |
| 20 | +### Starting Development Server |
| 21 | + |
| 22 | +```bash |
| 23 | +yarn gulp dev |
| 24 | +# Runs terriajs-server on port 3001, watches for changes, and incremental builds |
| 25 | +# This is the main command for day-to-day development |
| 26 | +``` |
| 27 | + |
| 28 | +### Build Commands |
| 29 | + |
| 30 | +```bash |
| 31 | +yarn gulp build # Development build with source maps |
| 32 | +yarn gulp release # Production build (optimized) |
| 33 | +yarn gulp watch # Watch mode for incremental builds only (no server) |
| 34 | +``` |
| 35 | + |
| 36 | +### Server Only |
| 37 | + |
| 38 | +```bash |
| 39 | +yarn start # Run server only on port 3001 (without build/watch) |
| 40 | +``` |
| 41 | + |
| 42 | +### Testing (packages/terriajs/) |
| 43 | + |
| 44 | +```bash |
| 45 | +cd packages/terriajs |
| 46 | +yarn gulp test # Run tests in all available browsers (auto-detected) |
| 47 | +yarn gulp test-firefox # Run tests in Firefox only |
| 48 | +yarn gulp build-specs # Build test specs without running them |
| 49 | +yarn gulp watch-specs # Watch and rebuild test specs |
| 50 | +``` |
| 51 | + |
| 52 | +Tests use Karma + Jasmine. Configuration in `packages/terriajs/buildprocess/karma-*.conf.js`. |
| 53 | + |
| 54 | +### Linting and Code Quality |
| 55 | + |
| 56 | +```bash |
| 57 | +yarn gulp lint # Run ESLint on root (index.js, lib/) |
| 58 | +yarn prettier # Format all files with Prettier |
| 59 | +yarn prettier-check # Check formatting without writing |
| 60 | + |
| 61 | +# For TerriaJS library: |
| 62 | +cd packages/terriajs |
| 63 | +yarn gulp lint # ESLint on lib/, test/ directories |
| 64 | +``` |
| 65 | + |
| 66 | +### Webpack Hot Reloading |
| 67 | + |
| 68 | +```bash |
| 69 | +yarn hot # Webpack dev server with HMR on port 8080 |
| 70 | +``` |
| 71 | + |
| 72 | +### Other Tasks |
| 73 | + |
| 74 | +```bash |
| 75 | +yarn gulp clean # Clean build artifacts |
| 76 | +yarn gulp render-index # Render index.html from index.ejs (with --baseHref option) |
| 77 | +yarn gulp write-version # Generate version.js from git hash/package versions |
| 78 | +``` |
| 79 | + |
| 80 | +## Architecture |
| 81 | + |
| 82 | +### Application Entry Points |
| 83 | + |
| 84 | +- `index.js` - Main application initialization (creates Terria instance, ViewState, registers catalog members) |
| 85 | +- `entry.js` - Webpack entry point |
| 86 | +- `plugins.ts` - Plugin registration (returns array of plugin promises) |
| 87 | +- `lib/` - Custom application code (Core, Views, Styles) |
| 88 | +- `wwwroot/` - Static assets and served files |
| 89 | +- `buildprocess/` - Webpack and build configuration |
| 90 | + |
| 91 | +### TerriaJS Library Architecture (packages/terriajs/lib/) |
| 92 | + |
| 93 | +The TerriaJS library follows a layered architecture: |
| 94 | + |
| 95 | +1. **Core** - Low-level utilities independent of UI/mapping libraries |
| 96 | +2. **Map** - Cesium/Leaflet mapping layer abstractions |
| 97 | +3. **Charts** - Charting layer (D3-based) |
| 98 | +4. **Models** - Heart of TerriaJS - catalog, data sources, formats (MobX-based reactive state) |
| 99 | +5. **Traits** - Define configurable properties for models (MobX observables) |
| 100 | +6. **ModelMixins** - Reusable behaviors mixed into models |
| 101 | +7. **ViewModels/ReactViewModels** - UI-related logic not in React components |
| 102 | +8. **ReactViews** - React UI components (styled with Sass/CSS Modules, migrating to styled-components) |
| 103 | + |
| 104 | +### Key Concepts |
| 105 | + |
| 106 | +**MobX Reactive State**: The model layer uses MobX observables and computed properties. Properties are reactive - changes automatically trigger UI updates through React components using MobX observers. |
| 107 | + |
| 108 | +**Catalog System**: |
| 109 | + |
| 110 | +- `Terria` - Root application state (single instance) |
| 111 | +- `Catalog` - Data catalog from config.json |
| 112 | +- `CatalogMember` - Base for all catalog items |
| 113 | +- `CatalogGroup` - Folders containing items |
| 114 | +- `CatalogItem` - Mappable items (WMS, GeoJSON, CSV, etc.) |
| 115 | +- `CatalogFunction` - Functions producing items (WPS, etc.) |
| 116 | + |
| 117 | +**Strata System**: Models support multiple "strata" (layers) of property values that are merged: |
| 118 | + |
| 119 | +- User stratum (highest priority) |
| 120 | +- Load stratum (from GetCapabilities, etc.) |
| 121 | +- Definition stratum (from catalog config) |
| 122 | + |
| 123 | +**Mapping Abstraction**: All mapping uses Cesium abstractions even in 2D Leaflet mode: |
| 124 | + |
| 125 | +- Raster layers → `ImageryProvider` |
| 126 | +- Vector layers → `DataSource` and `Entity` |
| 127 | + |
| 128 | +### Plugin System |
| 129 | + |
| 130 | +Plugins extend TerriaJS functionality. Add plugin imports to `plugins.ts`: |
| 131 | + |
| 132 | +```typescript |
| 133 | +const plugins: () => Promise<TerriaPluginModule>[] = () => [ |
| 134 | + import("terriajs-plugin-sample") |
| 135 | +]; |
| 136 | +``` |
| 137 | + |
| 138 | +Plugins are loaded before app state restoration in `index.js`. |
| 139 | + |
| 140 | +## Build System |
| 141 | + |
| 142 | +- **Webpack 5** for bundling |
| 143 | +- **Babel** for transpiling TypeScript/JSX to ES5 |
| 144 | +- **Sass** for styling (CSS Modules with camelCase exports) |
| 145 | +- Entry configured via `buildprocess/webpack.config.js` |
| 146 | +- TerriaJS-specific webpack config via `configureWebpackForTerriaJS` from terriajs package |
| 147 | +- Plugin webpack config via `buildprocess/configureWebpackForPlugins.js` |
| 148 | + |
| 149 | +## Configuration Files |
| 150 | + |
| 151 | +- `serverconfig.json` - Server configuration (port, proxy allowlist) |
| 152 | +- `wwwroot/config.json` - Application catalog configuration |
| 153 | +- `wwwroot/init/` - Initialization files for different data sources |
| 154 | +- `wwwroot/index.ejs` - HTML template (rendered to index.html by gulp task) |
| 155 | + |
| 156 | +## Version Management |
| 157 | + |
| 158 | +The `write-version` gulp task generates version info from git hash, package versions, and date. Version appears in `brandBarElements` in the UI. |
| 159 | + |
| 160 | +## Important Development Notes |
| 161 | + |
| 162 | +- **Node >= 20.0.0** required |
| 163 | +- Uses **Prettier** for code formatting (enforced via husky pre-commit hook) |
| 164 | +- **No PM2** - server runs in foreground (changed in 2023) |
| 165 | +- TerriaJS uses **MobX 6.x** and **TypeScript 5.x** (upgraded in v8.3.0) |
| 166 | +- React **18.3.1** in packages/terriajs, **16.14.0** in root (for compatibility) |
| 167 | +- When adding custom functionality, prefer putting logic in Models layer rather than UI |
| 168 | +- UI should be thin, domain logic belongs in Models/ViewModels |
| 169 | +- Computed properties should be pure functions |
| 170 | +- Avoid side effects and reactions in model code |
| 171 | + |
| 172 | +## Common Customization Points |
| 173 | + |
| 174 | +- `lib/Views/render.tsx` - Custom rendering logic |
| 175 | +- `lib/Styles/variables-overrides.scss` - Override TerriaJS Sass variables |
| 176 | +- `wwwroot/config.json` - Catalog configuration, branding, feature flags |
| 177 | +- `index.js` - Register custom catalog members, search providers, analytics |
| 178 | + |
| 179 | +## Working with TerriaJS Source |
| 180 | + |
| 181 | +When making changes to TerriaJS itself (in `packages/terriajs/`), the workspace setup allows local development. Changes are reflected via the workspace link without needing to publish to npm. |
0 commit comments