The Organization module provides an interface to retrieve organization and membership data. Since the adoption of Better Auth, all organization and membership mutations (creation, invitation, role updates) are handled exclusively by the Bun backend. The Go backend treats these tables as read-only data sources.
Core Concepts
- Organizations: Represent business entities or tenants. All data in the platform is siloed by
organization_id. - Members: Define the relationship between a User and an Organization, including their assigned role within that organization.
- Plans: Represent subscription tiers (Starter, Pro, Enterprise). Unlike identity data, Plan definitions are managed directly by the Go backend.
Architecture
Source of Truth
- Organizations & Members: Better Auth (PostgreSQL tables:
organizations,members). - Plans: Go Backend (PostgreSQL table:
plans).
Repository Pattern (Read-Only)
The Go repositories for Organizations and Members are strictly read-only. We use GORM to perform selection queries against the shared PostgreSQL database.Functional Requirements
1. Organization Retrieval
- Retrieve organization details by ID or Slug.
- List all organizations a specific User belongs to.
- Retrieve organization metadata (logo, settings).
2. Member Management (Query Only)
- List all members of an organization (with user details joined).
- Check a user’s role within an organization.
- Retrieve membership status and join date.
3. Subscription Plans
- List available subscription plans.
- Retrieve plan limits (Max Users, Max Products, etc.).
- Update plan definitions (Administrator only).
Data Models
Organization (organizations table)
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (ULID/UUID) |
name | string | Display name |
slug | string | URL-friendly identifier |
logo | string | URL to organization logo |
created_at | datetime | Creation timestamp |
Member (members table)
| Field | Type | Description |
|---|---|---|
id | string | Unique membership ID |
organization_id | string | Foreign key to organizations |
user_id | string | Foreign key to users |
role | string | Assigned role (owner, admin, member) |
created_at | datetime | Join date |
Plan (plans table)
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
name | string | Plan name (e.g., Enterprise) |
max_users | int | Limit on total members |
max_products | int | Limit on inventory items |
Implementation Details
Multi-Tenancy
Most Go services use theOrganizationID from the authenticated context (extracted from the Better Auth JWT) to scope database queries.
Authorization
Roles are defined in themembers table. The PermissionService in the Go backend queries this table directly and caches the result in Redis to ensure low-latency authorization checks across all Go modules.