VIP
For government partners and other stakeholders who should follow project activity and preview upcoming map layers, without the ability to make drastic edits.
activity.viewlayers.view_draft
Multi-Level Admin Capabilities
The problem
Many SeaSketch projects run for years. Over that time, the list of project administrators tends to grow. Today, every administrator has the same powers: they can change anything in the project, including map layers, sketching tools, reports, forums, surveys, and user management.
In practice, people are invited as admins for very different reasons:
- A small number of people are true project leads. They need full control and are responsible for how the project is set up.
- Government partners or other stakeholders are sometimes invited mainly as a symbolic recognition of their role. They should appear as administrators, but are not expected to reconfigure the project.
- Contractors and specialists often have a narrow job — for example, uploading data and designing map styles — and should not be able to change sketching tools, publish reports, or download survey results that may contain personal information.
A single admin role works well for many projects. For others, it creates a risk of unwanted changes or inappropriate access to sensitive data.
What this feature would do
Projects could opt into a more flexible admin model. Instead of a single “administrator” switch, a project would have:
Project Owners — a small set of people with full control. They can do everything an admin can do today, and they are the only ones who can decide who else gets which responsibilities.
Capabilities — specific powers that can be granted, such as editing map layers, publishing those layers, managing users, designing surveys, or exporting survey responses. Each capability unlocks a clear part of the admin dashboard.
Roles — ready-made bundles of capabilities that match common staff types (for example Data Manager or Community Manager). Owners can assign a role as a starting point, then add or remove individual capabilities when someone needs a custom mix.
This feature would be opt-in
A capabilities model gives more control, but it also adds real complexity to day-to-day project administration. Large cloud platforms (for example AWS IAM) use a similar approach, and keeping permissions straight can become a full-time job. Project Owners would need to decide who gets which roles and capabilities, debug cases where someone doesn't have the right capabilities to do their work, and periodically review whether those assignments still make sense. That overhead is why multi-level admin access would be optional.
Suggested roles
These roles are starting points for common situations on SeaSketch projects. Project Owners hold every capability plus the exclusive powers listed later — they are not shown as a “role” below.
Roles are flexible. If a VIP should also help with survey invites, an Owner can add surveys.facilitate without creating a new role. The person’s access is simply that role plus the extra capability.
Data Editor
For contractors or staff who upload data, maintain metadata, and design map styles. They work in the draft layer list; someone else decides when changes go live.
layers.view_draftlayers.edit
Data Manager
For a trusted data lead: everything a Data Editor can do, plus publishing layers and managing the geographies used for clipping and analysis.
layers.view_draftlayers.editlayers.publishgeography.manage
Planning Lead
For the people who set up sketching tools, attribute forms, and the analytical reports planners see when they draw.
layers.view_draftlayers.editgeography.managesketches.editsketches.managereports.editreports.publish
Community Manager
For the people who run participation and the project's public face: invites, groups, forums, and branding (name, logo, about page, languages, map extent).
activity.viewsettings.customizationusers.managelayers.view_draftlayers.editforums.manageforums.moderate
Survey Facilitator
For field staff coordinating survey data collection. They can monitor progress and limited response collection details, but not see individual responses for all users.
surveys.facilitate
Survey Administrator
For the people who own the survey program: designing surveys, managing invites, and working with response data — including exports that may contain personal information.
surveys.facilitatesurveys.editsurveys.access_responsessurveys.manage
What each role can do
| Capability | VIP | Data Editor | Data Manager | Planning Lead | Community Manager | Survey Facilitator | Survey Administrator |
|---|---|---|---|---|---|---|---|
activity.view | ● | — | — | — | ● | — | — |
settings.customization | — | — | — | — | ● | — | — |
users.manage | — | — | — | — | ● | — | — |
layers.view_draft | ● | ● | ● | ● | ● | — | — |
layers.edit | — | ● | ● | ● | ● | — | — |
layers.publish | — | — | ● | — | — | — | — |
geography.manage | — | — | ● | ● | — | — | — |
sketches.edit | — | — | — | ● | — | — | — |
sketches.manage | — | — | — | ● | — | — | — |
reports.edit | — | — | — | ● | — | — | — |
reports.publish | — | — | — | ● | — | — | — |
forums.manage | — | — | — | — | ● | — | — |
forums.moderate | — | — | — | — | ● | — | — |
surveys.facilitate | — | — | — | — | — | ● | ● |
surveys.edit | — | — | — | — | — | — | ● |
surveys.access_responses | — | — | — | — | — | — | ● |
surveys.manage | — | — | — | — | — | — | ● |
What only Project Owners can do
Some actions stay with Project Owners even when a project uses multi-level admin access. These are powers that change who is in charge, who can join, or that can permanently remove data.
| Reserved for Owners | Why |
|---|---|
| Assigning roles and capabilities | Only Project Owners decide who gets which roles or capabilities, and who else becomes an Owner. |
| Project access settings | Whether the project is public, invite-only, or admins-only; whether it appears in public listings; and whether major tools (forums, sketches, overlays) are hidden. |
| API and Mapbox keys | Keys that grant ongoing programmatic or mapping access outside day-to-day admin work. |
| Data retention | Settings that can permanently delete archived uploads. |
| Groups that carry admin capabilities | Membership of any group that already has capabilities assigned — so a Community Manager cannot escalate their own access by joining such a group. |
| Deleting the project | Removing the project entirely. |
Detailed list of admin functionality and matching capability assignment
Use this section when you want to check a specific part of the admin dashboard and see which capability (or Owner-only rule) covers it. Expand any area below.
Project settings
| Admin functionality | Capability |
|---|---|
| Name, description, logo, and logo link | settings.customization |
| About page | settings.customization |
| Supported languages | settings.customization |
| Map extent (the default map view) | settings.customization |
| Default map options (scale bar, legend) | settings.customization |
| Who can join / whether the project is listed publicly | settings.access (Owners only) |
| Hiding forums, sketches, or overlays from the main app | settings.access (Owners only) |
| Mapbox and project API keys | settings.keys (Owners only) |
Activity
| Admin functionality | Capability |
|---|---|
| Activity dashboard (visitors, popular layers, forum activity) | activity.view |
Users & groups
| Admin functionality | Capability |
|---|---|
| View participants and profiles | users.manage |
| Create, send, edit, and track invites | users.manage |
| Approve or deny access requests | users.manage |
| Create, rename, and delete groups; assign membership | users.manage |
| Make someone a Project Owner | Owners only |
| Ban someone from posting in forums | forums.moderate |
Data layers
| Admin functionality | Capability |
|---|---|
| View the draft (unpublished) layer list | layers.view_draft |
| Upload data and manage processing jobs | layers.edit |
| Add remote sources (ArcGIS, GeoJSON, and similar) | layers.edit |
| Organize folders and layer order in the draft list | layers.edit |
| Edit metadata and map styles | layers.edit |
| Control who can see each layer | layers.edit |
| Manage basemaps | layers.edit |
| Offline map packages (when enabled) | layers.edit |
| Publish draft layers so participants can see them | layers.publish |
| Change how long archived uploads are retained | settings.retention (Owners only) |
Geography & reports
| Admin functionality | Capability |
|---|---|
| Create, edit, and maintain geographies and clipping | geography.manage |
| Create reports and edit draft content | reports.edit |
| Publish reports for planners to use | reports.publish |
Sketch classes (sketching tools)
| Admin functionality | Capability |
|---|---|
| Create or delete a sketching tool | sketches.manage |
| Edit settings, attribute forms, and styles | sketches.edit |
| Configure geography clipping and analysis | sketches.edit |
| Assign the primary report to a sketching tool | reports.publish |
Forums
| Admin functionality | Capability |
|---|---|
| Create and organize forums; set who can read or post | forums.manage |
| Community guidelines | forums.manage |
| Hide posts, lock topics, ban posters | forums.moderate |
Surveys
| Admin functionality | Capability |
|---|---|
| Monitor survey progress and invite status (no answers) | surveys.facilitate |
| Design surveys and manage survey invites | surveys.edit |
| View, correct, and export responses | surveys.access_responses |
| Create or delete surveys; archive responses | surveys.manage |
Engineering blast radius
Today, project privilege is a single boolean: project_participants.is_admin, checked via session_is_admin(). Replacing it with Owners, 17 capabilities, and opt-in roles touches every site that currently asks “is this person an admin?” Inventory from the live schema and client, September 2026.
The bottom line is that hundreds of functional and user-interface gates will need to be upgraded to use this more complex authorization matrix. This upgrade process cannot be entirely automated, as each action will need to be slotted into an appropriate capability.
Server
Access control changes will impact
- 160 stored procedures that call
session_is_admin - 65 row-level security policies (45 tables)
- 302 GraphQL mutations (~84% admin-gated)
- 46 GraphQL computed fields that check admin
- 44 custom API plugins
Client
Access control changes will change behavior of
- 16 public project map tools
- 21 URL route families
- 10 admin dashboard sections
- 57 tools and settings in the admin interface
Test coverage and gaps
To execute changes that touch nearly every aspect of SeaSketch it will be necessary to radically improve our test coverage. It would not be surprising to land on 4x as many tests as we currently have to safely deploy this feature.
| Current State | Needed | |
|---|---|---|
| Server Tests |
~560 unit tests
Permission tests mostly “admin can do X, everyone else cannot.” |
~2,000 unit tests
About 4× today. Each of the 160 call sites and 45 gated tables needs several cases (right capability, wrong capability, none), not just admin vs everyone else — plus Owner/grant/opt-in helpers. |
| Client Integration Tests |
0 working
~90 Cypress scenarios remain in the repo. They are unmaintained and focused on surveys, not admin. |
~80 new browser scenarios
Capability-correct UI and routes, plus golden administrator paths. Browser only — not GraphQL. |
This opportunity to improve SeaSketch’s test suite should be taken advantage of. Right now we entirely lack working integration tests, and that means updates sometimes ship which break existing functionality. In 2022 we had a dedicated test engineer working on this test suite and that work fell into disrepair afterwards. It was hard to justify the monumental effort and cost of full test coverage back then. The situation has changed now.
- Capabilities-based access control simply cannot be implemented reliably without substantial test coverage.
- Tests are much easier to create and maintain using AI Agents.
- A full test suite makes it much easier to verify the products of AI code generation. Building SeaSketch using an agent-driven “software factory” is only feasible this way.
Given the circumstances, it makes sense to tackle improved test coverage as a separate work stream dependency to the access control work, to be done ASAP in 2026.
Technical details
Database — 160 functions, 65 policies
- 160 of 641 public SQL functions call
session_is_admin: 113 mutations/helpers, 46 computed columns, 1 trigger. - 65 of 97 RLS policies, on 45 of 51 RLS-enabled tables. 274 occurrences in
schema.sql. - Admin-gated tables include:
data_layers data_sources table_of_contents_items surveys survey_responses sketch_classes reports forums project_groups project_invites basemaps overlay_data_tables api_keys projects geography
- PostGraphile auto-CRUD (
updateDataLayer,createSurvey,deleteForum, …) has no admin check in its own SQL. It succeeds or fails because of the table policy. - New storage: project opt-in, Owners, and role/capability grants on people and groups.
grantAdminAccess/toggleAdminAccessbecome Owner-only and are no longer sufficient.
GraphQL API — 302 mutations, 44 plugins
- 302 mutations (255 without Relay
ByNodeIdaliases), 208 queries, 5 subscriptions. Roughly 84% of mutations are project-admin-gated. - By domain: layers/TOC/basemaps/offline 97; surveys/forms 67; users/invites/groups/ACL/keys 40; forums 22; sketches 20; reports 19; project settings 19; geography 15.
- 46 computed fields check
session_is_admin(Project.sessionIsAdmin,Project.mapboxSecretKey, invites, quota, visitor stats,User.isAdmin, …). - 44 custom PostGraphile plugins. 8 of them re-query
session_is_adminin TypeScript (geography, sketch styles, temporal metadata, reports, activity, hosted-tile UUIDs, map-access tokens). - Some mutations mix capabilities the proposal splits.
updateProjectis one input for name/logo (settings.customization), access mode and hidden tools (Owners only), and related fields.
Client — 10 admin sections, 57 tools, 21 routes
The admin SPA is all-or-nothing: AdminApp and ProjectAccessGate redirect unless sessionIsAdmin is true. There is no per-section gating.
| Route family | Capability |
|---|---|
/:slug/admin (settings) | Split: customization vs access vs keys |
/:slug/admin/activity | activity.view |
/:slug/admin/users | users.manage; make Owner is Owner-only; forum ban is forums.moderate |
/:slug/admin/data | layers.view_draft to enter; edit / publish / retention split inside |
/:slug/admin/geography | geography.manage |
/:slug/admin/sketching | sketches.edit / sketches.manage |
/:slug/admin/reports | reports.edit / reports.publish |
/:slug/admin/forums | forums.manage / forums.moderate |
/:slug/admin/surveys | Four survey capabilities on one screen |
/:slug/admin/offline | layers.edit |
/:slug/edit-basemap/:id | layers.edit |
/:slug/survey-editor/:id | surveys.edit |
Public map /:slug/app/… (overlays, sketches, forums, maps, about, settings) | Draft layers and unpublished sketch classes; admin chrome for any granted capability |
Settings, Data, Surveys, and Users each combine capabilities that must be split or field-checked. Superuser UI (/dashboard, featured project, hosting quota, project API keys) stays a separate axis.
Public map and tile auth
- 16 map tools: overlays, basemaps, sketching, reports, forums, about, admin entry, language, offline cache, help, profile, measure, scale bar, coordinates, legend, reset bounds.
- VIP / Data Editor must see draft overlays; other roles must not. That is new public-map behavior, not only new admin nav.
Project.mapAccessTokenis a JWT withrole: "admin" | "user". The pmtiles server uses that role to allow or deny draft and protected tiles.- Bookmark screenshots, overlay-engine requests, and object downloads inherit the same binary role.
Help refine this proposal
Add your comments or directly add new roles or capabilities to the spreadsheet below.