LogicSpike System Architecture & Data Flow

Last Updated: 2026-03-24 Status: Active Source of Truth

This document outlines the high-level architecture of the LogicSpike ecosystem, capturing how the independent microservices interact, how data moves across the network boundary, and how authorization is enforced at the edge.

1. Global Microservice Ecosystem (10,000 Foot View)

LogicSpike relies on a decoupled, multi-tenant architecture running primarily on Cloudflare Workers and Neon Serverless Postgres.

The Gateway acts as the singular ingress controller for the entire backend framework, shielding all internal microservices from direct external access and offloading computationally heavy authorization (JWT parsing) to the edge.

2. Authentication & Data Movement (PBAC Edge Enforcement)

One of the platform's core advantages is Asymmetric Edge Verification. The Identity system (Manager) is entirely decoupled from the Authorization enforcement (Gateway & Microservices).

How Auth Data Moves

1. The Issue: The Manager service owns the RS256 Private Key. It queries the DB for a human's Membership and Role, flattens them into [system:owner, blog:posts.update], and mints a signed JWT.
2. The Transit: The Dashboard stores this JWT and sends it as Authorization: Bearer <jwt>.
3. The Edge Verification: The Gateway holds the RS256 Public Key. It verifies the signature without touching the database.
4. The Handoff: The Gateway strips the JWT, unpacks the claims, and injects safe, trusted x- headers before forwarding the request to the internal microservice via Cloudflare Service Bindings.

3. Asynchronous Event Architecture (The Event Bus)

To keep services decoupled (e.g., the Blog Service shouldn't have to import the Communication Service's email code), the platform uses a pub/sub model for cross-domain orchestration.

4. Service Communication Map

A complete view of how every service talks to every other service — direct bindings vs event-driven.

5. Key Security Invariants

1. The x-gateway-key Requirement: No microservice (Blog, Media, Content) should ever be accessible publicly on the internet. They MUST reject any request that does not contain a valid x-gateway-key matching their environment variable. This ensures the Gateway (and its auth checks) cannot be bypassed.
2. Tenant Isolation: Every single database query in a localized microservice must include where(eq(table.tenantId, xTenantIdHeader)). Leakage of data across tenants is a critical failure.
3. Stateless Authorization: Backend services do not query the memberships or roles tables. They trust the x-user-permissions header array explicitly. If a user's permissions change, a new token must be issued.