User Module Functional Specifications

​

Overview

The User module in the Go backend has been refactored to be a read-only repository that queries the Better Auth PostgreSQL tables directly. This module no longer handles user creation, password management, or profile updates; these responsibilities have been moved to the Better Auth service running on the Bun monolith. The Go backend serves as a consumer of identity data, providing enriched user information to other microservices and modules within the Go ecosystem.

​

Data Model (Consumer View)

The User entity maps directly to the users (Better Auth core) and members (Better Auth organization) tables.

​

User Entity

• ID: Unique Identifier (nanoid generated by Better Auth)
• Email: Unique email address
• EmailVerified: Boolean status from Better Auth
• Name: User’s full name
• Image: URL to profile image
• IsAnonymous: Boolean flag for guest users
• Role: Platform-level role (user, admin, superadmin) from the Better Auth admin plugin
• Status Fields:
  • Banned: Boolean status
  • BanReason: Optional reason for account suspension
  • BanExpires: Timestamp for temporary bans
• Enriched Context:
  • OrganizationID: The active organization ID (from members table)
  • OrgRole: The user’s role in the organization (owner, admin, staff, viewer)
  • ManagerID: Optional reporting manager ID (from members custom field)
  • DepartmentID: Optional department ID

​

Functional Requirements

​

1. Retrieve User Details

• Input: User ID or Email.
• Logic:
  • Performs a direct query against the users table in PostgreSQL.
  • Joins with the members table to inject organization context if available.
• Output: Enriched User object.

​

2. Search Users by Organization

• Input: Organization ID.
• Logic: Join members and users tables to list all users belonging to a specific organization.
• Output: List of User objects with their organization roles.

​

3. Identity Verification (Stateless)

• Note: The User module provides the infrastructure to map JWT claims (from Authorization header) to local domain entities. No database lookup is performed for signature verification; only for supplemental data enrichment.

​

Architecture: Single Source of Truth

The User module adheres to a “Query-Only” pattern in the Go backend:

1. No Data Duplication: The Go backend does not maintain a local users table. It queries the users table managed by Bun/Better Auth.
2. No NATS Synchronization: Synchronization logic has been eliminated in favor of direct database queries, ensuring absolute consistency and zero lag.
3. Write Forwarding: All write operations (creating users, changing passwords, assigning roles) must be addressed to the Better Auth HTTP API on the Bun backend.

​

API Endpoints (Read-Only)

​

Deprecated Endpoints

The following endpoints have been DELETED from the Go backend and moved to Bun:

• POST /users (Use POST /api/auth/admin/create-user on Bun)
• PATCH /users/:id (Use POST /api/auth/admin/set-role on Bun)
• DELETE /users/:id (Use POST /api/auth/admin/remove-user on Bun)