clerk orgs Backend architecture

[eric-kitagawa]

Description

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Refactoring (code improvement without changing functionality)
• Documentation update
• Configuration/infrastructure change
• Performance improvement
• Test coverage improvement

Related Issue(s)

Closes #
Related to #

What Changed?

Testing & Validation

How this was tested

Screenshots/Recordings

Unfinished Work & Known Issues

• None, this PR is complete and production-ready
• The following items are intentionally deferred:

  • ---

  • ---

  • ---

Notes & Nuances

• ---

• ---

Pre-Merge Checklist

Code Quality

• Code follows the project's style guidelines and conventions
• Self-review completed (I've reviewed my own code for obvious issues)
• No debugging code, console logs, or commented-out code left behind
• No merge conflicts with the base branch
• Meaningful commit messages that explain the "why"

Testing & CI

• All CI checks are passing
• All new and existing tests pass locally
• Test coverage hasn't decreased (or decrease is justified)
• Linting passes without errors

Documentation

• Code is self-documenting or includes helpful comments for complex logic
• API documentation updated (if backend endpoints changed)
• Type definitions are accurate and up-to-date

Reviewer Notes

• Areas needing extra attention: ...
• Questions for reviewers: ...

[Dao-Ho]

This is a good start, and definitely one of the flows we want. But some things to consider.

What you have: whenever a new user gets created under an org, you insert that user into an existing org/hotel in our DB.

Some questions to consider:

1. What happens if a user is created before their org is created?
2. What happens if the org is created on clerk, and a member is created under that org, but it isn't in our internal database. How do we handle that now?

I think this should give you a good direction on improving this.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 101 lines in your changes missing coverage. Please review.
✅ Project coverage is 19.07%. Comparing base (87ced32) to head (1ef7bbf).

Files with missing lines	Patch %	Lines
backend/internal/repository/hotels.go	0.00%	35 Missing ⚠️
backend/internal/handler/clerk.go	0.00%	34 Missing ⚠️
backend/internal/utils/clerk.go	0.00%	11 Missing ⚠️
backend/internal/handler/utils.go	0.00%	9 Missing ⚠️
backend/internal/service/clerk/organizations.go	0.00%	8 Missing ⚠️
backend/internal/service/server.go	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##            main     #175       +/-   ##
==========================================
+ Coverage   0.62%   19.07%   +18.45%     
==========================================
  Files         78       48       -30     
  Lines       3218     2343      -875     
==========================================
+ Hits          20      447      +427     
+ Misses      3198     1881     -1317     
- Partials       0       15       +15     

Flag	Coverage Δ
backend	19.07% <0.00%> (?)
web	?

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
backend/internal/service/server.go	0.00% <0.00%> (ø)
backend/internal/service/clerk/organizations.go	0.00% <0.00%> (ø)
backend/internal/handler/utils.go	21.27% <0.00%> (ø)
backend/internal/utils/clerk.go	0.00% <0.00%> (ø)
backend/internal/handler/clerk.go	0.00% <0.00%> (ø)
backend/internal/repository/hotels.go	0.00% <0.00%> (ø)

... and 120 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[manueltorres0]

Update on the PR for clerk orgs.
Key changes:

• modified flow to handle organization created webhook, and organization membership creted webhook separetly
• added utility to hit Clerk API to create org when onboarding directly on selfserve

Debt:

• org deleted/updated webhook + membership deleted/updated webhook
• refactor the user sync script
• make onboarding use the utility
• redirect users that are not assigned to an association page

Current FLOW:
A)

1. Manager creates a Clerk org via clerk UI

B)

1. Manager creates a Clerk org on app

2. BE hits clerk to create org and makes the corresponding hotel

3. organization.created fires → hotel created in DB with org name and clerk_org_id

4. hotel id injected into clerk maintained FE accesible metadata

5. Manager auto-added as member → organizationMembership.created fires → user created in DB

6. Staff invited → accepts → organizationMembership.created fires → staff user created in DB

7. If hotel not found during step 3/4 → 503 returned → Clerk retries until hotel exists