Skip to main content
DEV MODE
Running from branch dev
isomorphiq
Register

Documentation

Browse system documentation and architecture references.

Architecture

architecture.md

Architecture

This system is a microservice-oriented platform with a unified gateway and edge routing.

Topology Summary

Core layers:

  1. Edge layer: Traefik-based edge routing and ingress controls.
  2. Gateway layer: a unified HTTP gateway (services/gateway) for API and frontend traffic.
  3. Service layer: domain microservices (tasks, auth, profiles, context, workflows, notifications, etc).
  4. UI layer: appshell plus federated frontend modules.

Microservices

Domain responsibilities are separated into dedicated services and packages. Typical service responsibilities include:

  • authentication and authorization,
  • task lifecycle and queue operations,
  • workflow execution,
  • context/profile management,
  • analytics and notifications.

The gateway resolves incoming routes and dispatches requests to the appropriate backend service.

Gateway

services/gateway is the front door for:

  • API route handling,
  • authorization checks,
  • service dispatch/proxying,
  • selected direct endpoints (health, environment, branch, metrics, docs APIs, etc),
  • websocket upgrade routing for supported endpoints.

It also mediates internal service calls and normalizes client-facing behavior.

Edge, Linode Router, and Traefik

At the edge, Traefik configuration under edge/traefik/ defines dynamic routing and module entry points.

In a Linode deployment model, the Linode router and edge proxy tier typically provide:

  • ingress routing from public endpoints,
  • TLS termination and forwarding rules,
  • controlled path forwarding toward the gateway and service endpoints.

Traefik is the programmable edge component used to express and evolve those rules.

WireGuard Tunnel

WireGuard is used as the secure tunnel layer between network segments/environments. In this model it provides:

  • encrypted transport across hosts,
  • restricted service reachability,
  • controlled connectivity between edge and internal service networks.

This reduces exposed surface area and keeps service-to-service traffic constrained.

Frontend Federation

Frontend features are split into federated modules under federation/modules/*.

The appshell loads remotes and composes them into a single runtime route surface. This allows independent module evolution while maintaining a unified navigation experience.

Documentation Flow

The /docs route renders markdown sourced from ./docs through gateway docs endpoints:

  • GET /api/docs/tree
  • GET /api/docs/content?path=<relative-markdown-path>

This keeps authored docs and rendered docs aligned.