This document details the runtime architecture of the Gremlin platform, illustrating how client surfaces interact with backend application services, identity providers, and data persistence layers.

​
Architecture Overview

Platform Runtime Architecture
An interactive, zoomable version of this diagram is available at platform-runtime.html.

​
System Topology & Boundaries

The Gremlin platform runtime is organized across three primary architectural tiers and external integrations:

​
1. Client Surfaces

  • SolidStart Panel (frontend/solidstart): Dedicated web administration and product dashboard providing full table views, management flows, and responsive desktop workflows. Communicates directly with the Go Core API via REST/GraphQL using Better Auth session credentials.
  • Astro Platform (frontend/astro): Public and tenant web surfaces built with Astro and Qwik components for high performance, content delivery, and interactive web sessions.
  • FieldForce Mobile (mobile/flutter): Offline-first mobile client built with Flutter and local SQLite. Operates seamlessly in low or zero connectivity environments, syncing bidirectionally via PowerSync.

​
2. Application Services

  • Bun Auth/API (backend/bun - Port 3100): Fast TypeScript runtime running Hono and Better Auth. Serves as the central identity authority, handling sign-up, sign-in, session tokens, organization hierarchies, members, invitations, and API key lifecycles.
  • Go Core API (backend/go - Port 8080): High-performance core backend built on Echo and GraphQL (gqlgen). Enforces business logic, domain boundaries, transactional rules, and audit logging. Go acts as a read-only consumer of identity tables and the primary authority for domain mutations.
  • PowerSync Service: Dedicated bidirectional synchronization bridge. Ingests PostgreSQL data via logical replication and provides continuous, resilient sync streams to FieldForce mobile clients.

​
3. Platform Data & Storage

  • PostgreSQL (Port 5432): Single source of truth holding both identity/auth schemas (managed by Bun/Better Auth) and domain state schemas (managed by Go GORM/SQL migrations).
  • Redis (Port 6379): High-speed memory store utilized by Bun Auth and Go services for distributed rate limiting, token caches, and mutation idempotency keys.
  • SeaweedFS: S3-compatible distributed object storage supporting public assets as well as private, signed URL uploads for activity attachments and media.
  • NATS (Port 4222): Message bus for decoupled asynchronous events, transactional outbox publishing, and background worker consumers.

​
Core Runtime Flows

​
1. Primary Request Flow

For web clients (SolidStart Panel and Astro Platform):
  1. Authentication: Client applications authenticate against the Bun Auth server (:3100), receiving session cookies or bearer tokens.
  2. Business API Call: The frontend sends REST or GraphQL requests directly to the Go Core API (:8080) along with Better Auth credentials.
  3. Domain Execution: Go validates the session/token, enforces authorization policies (RBAC/ACL), and executes business transactions against PostgreSQL.

​
2. Identity Boundary

The system establishes a clean separation of concerns for identity data:
  1. Authentication & Session Exchange: Users sign in via Bun Auth (:3100). FieldForce Mobile clients exchange their initial session for a long-lived JWT app token with offline grace support.
  2. Read vs. Write Authority: Bun with Better Auth owns and mutates user, session, organization, and member records in PostgreSQL.
  3. Direct Database Reads: Go Core API (:8080) directly queries PostgreSQL to inspect user and organization memberships without proxying through Bun for read paths.
Architectural Principle (ADR-0006): Bun with Better Auth is the sole writer of identity tables (user, session, organization, member). The Go Core API operates as a read-only consumer of identity tables via direct DB queries, preventing foreign key drift while eliminating unnecessary synchronous RPC hops.

​
3. Offline-First & Asynchronous Sync

Field operations rely on autonomous mobile workflows where continuous internet access cannot be guaranteed:
  • Downlink (PostgreSQL to Mobile): PostgreSQL streams changes to the self-hosted PowerSync service via native logical replication. PowerSync partitions and synchronizes records down to the client’s local SQLite database according to tenant sync rules.
  • Uplink (Mobile to Server): Changes made offline queue up in local SQLite. When connectivity is restored, the queue syncs to PowerSync, which proxies mutations to Go Core API at POST /api/mobile/sync/upload.
  • Write Authority: Go Core API remains the ultimate write authority, validating invariants and conflict-resolution rules before committing changes to PostgreSQL.
  • Media Uploads: Large binaries and task attachments upload directly from clients to SeaweedFS using presigned S3 URLs, minimizing backend memory footprint.

​
Component Reference