This project consists of multiple packages in a monorepo configuration.
This is the core server package. It include a GraphQL API server based on Postgraphile, and all database migrations. It also includes an exported node api (@seasketch/api) that can be used by other services to access and manipulate application data.
Single-page-app style javascript client built using Create React App.
CDK App that defines the production hosting infrastructure
Provides a reusable method of connecting to the production SeaSketch database from Lambda services.
Lambda microservice for updating project and survey invite status based on SNS notifications from AWS SES.
Prerequisites: Node from .nvmrc, and a Compose-compatible runtime (Docker Desktop, OrbStack, Colima, or Podman with its compose plugin). Nothing starts when you open the folder.
From the repo root:
npm run bootstrap
npm run build
npm run setup
npm run devnpm run bootstrap is npm install at the repo root. One lockfile covers the workspace. npm run build is tsc -b over every workspace package plus the two bundling steps tsc cannot run (the fgb-source tsup bundle and the overlay-engine worker). npm run build:api builds the API and only the packages its tsconfig references; npm run build:client-libs builds the packages the client imports.
Workspace packages load from their gitignored dist/ output, so a fresh install needs npm run build before npm run dev. npm run dev checks for that output and exits with that instruction if a package has not been built. It starts Postgres and Redis, then the API, the client, the watchers, and the data-tables, spatial-uploads, and subdivision workers, in the foreground. Those workers recompile and restart when their code changes. Ctrl-C stops the host processes. It does not enable E2E_TEST_MODE; a normal development API uses Auth0 login. The smoke suite turns test mode on itself, and it starts the same three workers. The tests do not call them yet. If one of them fails to listen, the job fails.
npm run logs follows every service. npm run logs -- api follows one. Files are .logs/<service>.log, rotated at 20 MB. npm run status prints which services are listening. npm run setup -- --reset replaces the local database with the golden snapshot.
npm run e2e runs the Playwright suite in packages/e2e. It restores the golden snapshot into seasketch_e2e and starts its own API and client, separate from npm run dev. Chromium is a separate download from npm install. Once per machine, and again after a Playwright upgrade:
npm exec --workspace @seasketch/e2e -- playwright install chromiumIn Cursor or VS Code, Terminal > Run Task > Dev: core runs that same command in one terminal, and opens two more that follow npm run logs -- client and npm run logs -- db-watch. CI runs npm run dev -- --ci, which skips the watchers and runs the API from its build.
Follow ENV.md for the variables. Human login needs an Auth0 tenant you control; AUTH0.md is the setup.
This project is managed using the GitHub Flow pattern and GitHub Actions. To make changes...
- Do work on a feature branch and create a pull request
- Ensure automated checks pass, including unit and end-to-end tests
- Checkout the Deployment Options Summary to see how changes will impact production.
- Within GitHub, go to Actions / Create Deployment and run the workflow on your branch.
In general, try not to merge directly into master, but if you do, make absolutely certain all changes are deployable. When using a feature branch, it's easy to roll back a bad deployment. All you need to do is run the Create Deployment workflow on master, which should be ready to deploy if the rules are followed. Alternatively, you could create a new branch from a previous commit if broken changes are at the HEAD.
This summary is generated for every commit and will flag what services will be updated.