Feat/user interactions

[Prajjawalk]

Summary by CodeRabbit

Release Notes

• New Features

  • Introduced teams for organizing users within organizations
  • Added invitation system for member onboarding with email notifications
  • Launched alert subscriptions with multiple frequency options (immediately, daily, weekly, monthly)
  • Implemented password reset functionality
  • Added feedback and commenting capabilities
  • Enabled location-based access controls and team scoping
  • Implemented hierarchical location structures with ancestor location tracking
  • Added alert notification emails and digest summaries

• Documentation

  • Generated interactive API documentation with GraphQL schema reference

• Chores

  • Updated build and Docker configuration

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 99fd87d3-d278-4b1c-a586-dc0ac15ddd3a

📥 Commits

Reviewing files that changed from the base of the PR and between 3a85a10 and b7368f3.

📒 Files selected for processing (46)

• .claude/settings.json
• .dockerignore
• Dockerfile
• package.json
• prisma/migrations/20260319000000_add_teams_and_evolve_orgs/migration.sql
• prisma/migrations/20260319010000_rename_active_team_to_default_team/migration.sql
• prisma/migrations/20260319020000_fix_duplicate_org_slugs/migration.sql
• prisma/migrations/20260319202006_fix_duplicate_org/migration.sql
• prisma/migrations/20260323165357_add_ancestor_ids/migration.sql
• prisma/migrations/20260324131311_add_invitations/migration.sql
• prisma/schema.prisma
• prisma/seed.ts
• scripts/backfill-locations.ts
• scripts/build-docs.ts
• src/docs/docs.html
• src/docs/index.ts
• src/index.ts
• src/lib/auth.ts
• src/resolvers/alert.resolver.ts
• src/resolvers/auth.resolver.ts
• src/resolvers/event.resolver.ts
• src/resolvers/feedback.resolver.ts
• src/resolvers/index.ts
• src/resolvers/invitation.resolver.ts
• src/resolvers/location.resolver.ts
• src/resolvers/notification.resolver.ts
• src/resolvers/organisation.resolver.ts
• src/resolvers/signal.resolver.ts
• src/resolvers/subscription.resolver.ts
• src/resolvers/team.resolver.ts
• src/resolvers/user.resolver.ts
• src/schema/index.ts
• src/schema/typeDefs/mutation.ts
• src/schema/typeDefs/query.ts
• src/schema/typeDefs/types/alert.ts
• src/schema/typeDefs/types/invitation.ts
• src/schema/typeDefs/types/location.ts
• src/schema/typeDefs/types/organisation.ts
• src/schema/typeDefs/types/team.ts
• src/schema/typeDefs/types/user.ts
• src/services/messaging/templates.ts
• src/utils/auth-guard.ts
• src/utils/env.ts
• src/utils/geo-resolve.ts
• src/utils/location-scope.ts
• tsconfig.build.json

---

📝 Walkthrough

Walkthrough

This PR introduces comprehensive multi-tenancy support, geographic location hierarchies, and team-based access control. It adds organizations, teams, invitations, and alert subscriptions with scoped location filtering, geospatial utilities for location resolution and ancestry computation, password reset functionality, a feedback and comments system, and build-time documentation generation from the GraphQL schema.

Changes

Cohort / File(s)	Summary
Database Schema & Migrations prisma/schema.prisma, prisma/migrations/...	Six new migrations add organizations with slugs/timestamps, teams and team membership scoping, invitations with expiry/token mechanics, location ancestor tracking via TEXT[] arrays, and database constraint renames. Schema extended with user defaultTeamId, organization timestamps/slug/active flags, team/invitation relations, and location ancestorIds with GIN indexing.
Geospatial & Location Utilities src/utils/geo-resolve.ts, src/utils/location-scope.ts	New modules provide PostGIS-based location resolution (resolveLatLngToLocation, createPointLocation, createRegionFromPoints), ancestor chain computation, location descendant expansion, and team-scoped Prisma where filter builders for signal/event queries.
GraphQL Resolvers — Core Data src/resolvers/organisation.resolver.ts, src/resolvers/team.resolver.ts, src/resolvers/invitation.resolver.ts	New resolvers implement organization CRUD, team management with lead/admin authorization, and invitation workflows (create/accept/resend/cancel) with email sending and token generation.
GraphQL Resolvers — Queries & Mutations src/resolvers/alert.resolver.ts, src/resolvers/event.resolver.ts, src/resolvers/signal.resolver.ts	Updated to add teamId filtering, location-based queries (alertsByLocation, eventsByLocation, signalsByLocation), team membership checks, lat/lng → location resolution, and expanded location ancestry in alert fan-out.
GraphQL Resolvers — Subscriptions & Notifications src/resolvers/subscription.resolver.ts, src/resolvers/notification.resolver.ts	New subscription management with CRUD operations; notification mutations for bulk creation, alert subscriber fan-out, and frequency-based digest emails with per-user aggregation and PostGIS convex-hull region creation.
User & Auth Features src/resolvers/user.resolver.ts, src/resolvers/auth.resolver.ts, src/lib/auth.ts	Added defaultTeam and teamMemberships fields to User; new password reset mutations with throttling and email sending; defaultTeamId added to auth config as non-input field.
Feedback & Comments src/resolvers/feedback.resolver.ts	New resolver module with mutations and field resolvers for user feedback, comments, nested replies, and tag relationships; ownership/role-based authorization with validation constraints.
GraphQL Type Definitions src/schema/typeDefs/...	Added new GraphQL types/enums for organisations, teams, invitations, alert subscriptions (with Channel and Frequency enums), and location ancestry; extended mutations with 30+ new fields for team/org/invitation/subscription/feedback/auth operations.
Documentation Build & Serving scripts/build-docs.ts, src/docs/docs.html, src/docs/index.ts, src/index.ts	New build script generates GraphQL documentation HTML from schema introspection; statically-generated docs.html served by updated docs router (schema parameter removed); docs router converted to async with file-existence checks and fallback runtime generation.
Seed & Backfill Scripts prisma/seed.ts, scripts/backfill-locations.ts	Seed refactored to support location seeding with geographic hierarchies (country→states→districts) and environment-based admin credentials; new backfill script resolves missing locationId for signals and events via point lookup, text matching, or convex-hull region creation.
Email Templates & Messaging src/services/messaging/templates.ts	Expanded with new exported template functions for organization invite, team notifications, password reset, alert notifications, and frequency-based digest emails with reusable HTML helpers.
Configuration & Build .claude/settings.json, .dockerignore, Dockerfile, tsconfig.build.json, package.json, src/utils/env.ts, src/utils/auth-guard.ts	Added .beads and .claude to docker ignore; Dockerfile copies generated docs.html; new tsconfig.build.json disables declaration maps/source maps; build script runs docs generation before TypeScript compilation; moved @graphql-tools/schema to devDeps; added ADMIN_EMAIL/ADMIN_PASSWORD env vars and resolveTeamMembership auth helper.
Resolver Integration src/resolvers/index.ts, src/schema/index.ts	Imported and registered new resolver modules (organisation, team, feedback, invitation, subscription) and schema type definitions into aggregated exports.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Server
    participant Prisma
    participant PostGIS
    participant EmailProvider

    Client->>Server: inviteUser(email, orgId, teamId?)
    Server->>Prisma: findUnique organisation
    Server->>Prisma: findUnique user (by email)
    alt User exists
        Server->>Prisma: create invitation + synthetic record
    else User not found
        Server->>Prisma: create invitation with 7-day expiry
        Server->>EmailProvider: send invite email
        EmailProvider-->>Client: email delivered
    end
    Server-->>Client: Invitation

    Client->>Server: acceptInvite(token)
    Server->>Prisma: findUnique invitation by token
    alt Token valid & not expired
        Server->>Prisma: create user via auth
        Server->>Prisma: create organisationUsers + teamMembers
        Server->>Prisma: mark invitation accepted
    else Invalid or expired
        Server-->>Client: GraphQLError (BAD_USER_INPUT)
    end
    Server-->>Client: true

    Client->>Server: queryAlerts(teamId)
    Server->>Prisma: findMany teamLocations
    Server->>PostGIS: expand location IDs + descendants
    Server->>Prisma: findMany alerts (filtered by location scope)
    Server-->>Client: [Alert!]!

    Client->>Server: createAlert(event, triggeredAt, severity)
    Server->>Prisma: create alert
    Server->>Prisma: findMany subscriptions (frequency: immediately, location match)
    Server->>Prisma: createMany userAlerts + notifications
    Server->>EmailProvider: send alert notification (async)
    EmailProvider-->>Client: email queued
    Server-->>Client: Alert

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• feat: multi-tenancy with orgs, teams, and location scoping #5: Implements identical multi-tenancy schema/migrations (organizations, teams, invitations), resolver modules, location-scope/geo-resolve utilities, and docs build changes at the code level.
• update seed.ts, resolvers and typeDefs based on latest schema #1: Overlapping changes to seed.ts, multiple GraphQL resolvers (alerts, auth, events, signals, notifications, locations), and schema/typeDefs files with shared access-control patterns.
• Add: GeoJSON + email support #2: Shared code-level changes to email/messaging stack (templates, env vars, providers) and geospatial support (location resolvers, GeoJSON scalars) with overlapping modifications to templates.ts and env.ts.

Poem

🐰 A rabbit hops through teams and towns,
With slugs that slug through org renowns,
Invites now flow on wings of mail,
And locations find their ancestral trail.
Geography blooms in PostGIS light,
While scopes keep access tight and right! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/user-interactions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}