|
| 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 | +A GraphQL API for querying and analyzing NZSHM (New Zealand Seismic Hazard Model) composite inversion solutions. Built with Flask + Graphene, deployed as an AWS Lambda function via the Serverless Framework using Docker/ECR containers. |
| 8 | + |
| 9 | +## Common Commands |
| 10 | + |
| 11 | +### Setup |
| 12 | +```bash |
| 13 | +corepack enable && yarn set version berry |
| 14 | +yarn install |
| 15 | +poetry install |
| 16 | +yarn sls dynamodb install # requires Java |
| 17 | +``` |
| 18 | + |
| 19 | +### Running Locally |
| 20 | +```bash |
| 21 | +# Start local DynamoDB and S3 (separate terminals or backgrounded) |
| 22 | +npx serverless dynamodb start --stage local |
| 23 | +npx serverless s3 start |
| 24 | + |
| 25 | +# Start the API server |
| 26 | +SLS_OFFLINE=1 poetry run yarn sls wsgi serve |
| 27 | +``` |
| 28 | + |
| 29 | +### Testing |
| 30 | +```bash |
| 31 | +poetry run pytest # all tests |
| 32 | +poetry run pytest tests/test_file.py # single file |
| 33 | +poetry run pytest tests/test_file.py::test_function_name # single test |
| 34 | +poetry run pytest -m "not slow" # skip slow tests |
| 35 | +poetry run tox # full test suite via tox |
| 36 | +``` |
| 37 | + |
| 38 | +### Linting & Formatting |
| 39 | +```bash |
| 40 | +poetry run tox -e lint # flake8 + mypy |
| 41 | +poetry run tox -e format # isort + black |
| 42 | +poetry run tox -e audit # pip-audit security scan |
| 43 | +``` |
| 44 | + |
| 45 | +### Deploy |
| 46 | +```bash |
| 47 | +poetry export --without-hashes --format=requirements.txt > requirements.txt |
| 48 | +BUILDX_NO_DEFAULT_ATTESTATIONS=1 yarn sls deploy --stage dev --region ap-southeast-2 |
| 49 | +``` |
| 50 | + |
| 51 | +## Architecture |
| 52 | + |
| 53 | +### Request Flow |
| 54 | +``` |
| 55 | +API Gateway (API key auth) → Lambda handler (handler.py) |
| 56 | + → Flask app (solvis_graphql_api.py) → GraphQL schema (schema.py, QueryRoot) |
| 57 | + → Resolvers → cached.py (LRU-cached data loading) → solvis/nzshm libraries |
| 58 | + → DynamoDB (metadata via pynamodb) + S3 (binary blobs via boto3) |
| 59 | +``` |
| 60 | + |
| 61 | +### Key Modules |
| 62 | + |
| 63 | +- **`solvis_graphql_api/schema.py`** — Root GraphQL schema (`QueryRoot`). All top-level query fields defined here. |
| 64 | +- **`solvis_graphql_api/composite_solution/`** — Core domain logic: |
| 65 | + - `schema.py` — Pagination (relay cursors), filtering orchestration, connection builders |
| 66 | + - `cached.py` — LRU-cached functions for loading CompositeSolution archives and running filtered queries. Performance-critical. |
| 67 | + - `filtered_ruptures_args.py` — GraphQL input types for filtering |
| 68 | + - `filter_set_logic_options.py` — Union/Intersection set operations for combining location and fault filters |
| 69 | +- **`solvis_graphql_api/data_store/`** — DynamoDB + S3 dual-storage layer. `BinaryLargeObject` stores metadata in DynamoDB and binary data in S3. |
| 70 | +- **`solvis_graphql_api/color_scale/`** — Matplotlib-based color scale generation for visualization |
| 71 | +- **`solvis_graphql_api/scripts/cli.py`** — CLI for uploading composite solution archives to DynamoDB/S3 |
| 72 | + |
| 73 | +### Domain Dependencies |
| 74 | +- **solvis** — Inversion solution analysis (rupture filtering, geometry, fault sections) |
| 75 | +- **nzshm-model** — Source logic trees and model version data |
| 76 | +- **nzshm-common** — Location database and shared utilities |
| 77 | + |
| 78 | +## Environment Variables |
| 79 | + |
| 80 | +| Variable | Purpose | Default | |
| 81 | +|---|---|---| |
| 82 | +| `SLS_OFFLINE` | Set to `1` for local serverless | — | |
| 83 | +| `TESTING` | Set to `1` for test environment | — | |
| 84 | +| `REGION` | AWS region | `us-east-1` | |
| 85 | +| `DEPLOYMENT_STAGE` | Stage name (local/dev/test/prod) | `LOCAL` | |
| 86 | +| `S3_BUCKET_NAME` | S3 bucket for blob storage | `nzshm22-solvis-graphql-api-local` | |
| 87 | +| `LOGGING_CFG` | Path to logging YAML config | — | |
| 88 | + |
| 89 | +## CI/CD |
| 90 | + |
| 91 | +GitHub Actions workflow (`.github/workflows/dev.yml`) runs on PRs to `main` and `deploy-test`. Uses shared workflow from `GNS-Science/nshm-github-actions` for Python 3.12 test runs. |
0 commit comments