​
System Architecture & Integration

​
Overview

The Gremlin project is built as a hybrid microservices platform. It leverages a centralized identity management system with distributed business logic across discrete runtimes.

​
1. Core Runtimes

RuntimeTechnologyResponsibility
Bun MonolithTypeScript / Hono / PostgreSQLIdentity Management (Better Auth), Admin Services, and UI Adapters.
Go BackendGolang / Echo / PostgreSQLHigh-performance business modules (Orders, CRM, Invoices, Leave Management).

​
2. Shared Source of Truth (Identity)

The platform adopts a Shared Database Pattern for identity. Better Auth, running on the Bun monolith, is the exclusive authority for managing users, organizations, and sessions.

​
Key Integration Rules

  1. Mutations via Bun: All user registrations, role assignments, and organization changes MUST go through the Bun backend’s Better Auth APIs.
  2. Queries via Direct DB: Go services query the shared PostgreSQL tables (users, members, organizations) directly for read-only lookups.
  3. Stateless Security: Authentication is managed via stateless JWTs signed with a shared BETTER_AUTH_SECRET.

​
3. High-Level Communication Flow

High-Level Communication Flow

​
4. Database Strategy

The platform uses a “Fit-for-Purpose” database strategy:
  • PostgreSQL: Used for Identity (Better Auth) and all Relational Go modules (Leave, CRM, etc.).
  • MongoDB: Used by the Bun monolith for configuration and high-availability session logs.
  • Redis: Shared distributed cache for rate-limiting, idempotency, and permission caching.

​
5. Microservice Decoupling

Services are decoupled through:
  • Shared Identity Tables: Direct access avoids expensive and fragile synchronization logic.
  • NATS Message Bus: Domain-specific events (e.g., order.created) allow services to react without direct Coupling.
  • Hexagonal Architecture: Both Bun and Go services strictly separate core domain logic from infrastructure details.

​
6. Security Model

  • Authentication: JWT-based (HS256). Token signature verified at the boundary of every service.
  • Authorization: Role-Based Access Control (RBAC). Roles are resolved from Better Auth tables and mapped to service-specific permissions.
  • Data Isolation: Multi-tenancy is enforced at the query level using organization_id filters.