Milesoft Platform Architecture Overview

This document provides a comprehensive overview of the Milesoft Platform's architecture, service topology, multi-tenant isolation, and core integration flows. It is designed to help client developers building full-stack applications understand how their services, the Milesoft Gateway, and backend microservices interact to deliver a seamless, secure experience.

1. High-Level Architecture

The Milesoft Platform is engineered as a secure, distributed, multi-tenant microservices ecosystem. Rather than communicating directly with individual backend microservices, client applications interact with the platform through a centralized Milesoft Gateway. 

               +--------------------------------------+
               |            Client Tier               |
               | (React Web | React Native | CLI/MCP) |
               +--------------------------------------+
                                  |
                                  | HTTP/HTTPS
                                  v
               +--------------------------------------+
               |          Milesoft Gateway            |
               |    (OAuth2, JWT Decryption, Routing) |
               +--------------------------------------+
                                  |
         +------------------------+------------------------+
         |                        |                        |
         v                        v                        v
+------------------+     +------------------+     +------------------+
|Identity Provider |     |   Graph Engine   |     |  Layout Engine   |
| (Identity & Auth)|     |(Relational Graph)|     | (Template Engine |
|                  |     |                  |     |   & Webhooks)    |
+------------------+     +------------------+     +------------------+
         |                        |                        |
         v                        v                        v
+------------------+     +------------------+     +------------------+
| Messaging Engine |     |   Games Engine   |     |   GCP Services   |
|(SMS, Push, Email)|     |  (Progression,   |     | (Firestore, Run, |
|                  |     |  Leaderboards)   |     |  Cloud Storage)  |
+------------------+     +------------------+     +------------------+

Core Responsibilities:

  • The Gateway: Acts as the single entry point. It manages SSL/TLS termination, rate limiting, and route forwarding based on path prefixes (e.g., forwarding /api/v2/auth/* to the Identity Provider). More importantly, it acts as a secure firewall that decodes incoming JWT Access Tokens and populates standard downstream headers representing the verified user, application, and tenant account.
  • Backend Microservices: Specialized services that run inside Google Cloud Run. They are private, headless, and accept commands and queries exclusively from the Gateway.

2. Platform Service Topology

The backend consists of several independent microservices, each exposing robust REST endpoints and integrated via strongly-typed Java SDKs.

2.1 Identity, Directory, & Auth (Identity Provider)

The core identity provider of the platform. It handles authentication, access control lists (ACLs), user types, and application registrations.

  • Identity Management: Supports dual user flows (Admins/Super-Admins vs. Tenant-level users). It manages custom roles, user settings JSON Blobs, and MFA verification.
  • Integrations: Handles secure OAuth credentials and endpoints for external third-party systems (such as QuickBooks, Square, or LinkedIn).
  • API Keys & Robot Accounts: Provides support for generating, introspecting, and rotating non-user-bound programmatic API keys for service-to-service communication.

2.2 Relational Graph Engine (Graph Engine)

A high-performance social topology and relationship manager.

  • Graph Database Mapping: Models individuals as "nodes" and their social or business connections as "edges" with rich, customizable metadata.
  • Render Pipeline: Exposes API tools to generate dynamic, interactive layouts (horizontal, vertical, or grid) rendered as SVG files for front-end consumption (used heavily in Milesoft Connections).
  • Graph Ownership: Allows configuration settings to toggle whether the contacts graph is globally tenant-owned or strictly owned by individual users.

2.3 Layout & Webhook Engine (Layout Engine)

A low-latency, dynamic layout compiler and execution environment built around Shopify Liquid rendering.

  • Dynamic PDF & Document Generation: Stores system-level and tenant-specific Liquid templates. Compiles templates on-the-fly using merge-data maps to produce structured HTML, text, or PDFs.
  • Webhook Routing: Manages outbound webhook endpoints, retry parameters, and triggers. Enables external client systems to register event-based callbacks.

2.4 Messaging & Alerts (Messaging Engine)

A cross-channel messaging orchestrator.

  • Delivery Routing: Evaluates recipient notification settings and routes alerts across three primary channels: SMS (via Twilio), Push Notifications (via Google Firebase Cloud Messaging), and transactional Email (via SendGrid or Google Cloud Mail).
  • Tenant Scoping: Isolates notifications to ensure distinct branding, sender profiles, and template configurations per tenant account.

2.5 Gamification & Progression (Games Engine)

The progress, leaderboard, and gamification suite powering Milesoft's interactive modules (e.g., Milesoft Sudoku, Milesoft Words, Milesoft Dots).

  • Progression Tracking: Tracks daily activities, levels, difficulty tiers, completion times, and user score matrices.
  • Leaderboard Engine: Calculates median, mean, and high scores across rolling weekly or permanent timelines.

3. Core Architectural Flows

3.1 Authentication & Context Propagation

All interactions with the Milesoft Platform depend on OAuth2 with Proof Key for Code Exchange (PKCE).

Token Lifecycle

  1. Interactive Handshake: The developer or end-user logs in (via the CLI or browser).
  2. Token Issuance: The central authorization server verifies credentials and MFA, returning a short-lived, low-risk JWT Access Token (expiring in 15 minutes) and a long-lived, high-risk Refresh Token (secured in the native OS Keychain or central database).
  3. Gateway Translation: When a client application sends a request, it includes the Access Token as a bearer header: Authorization: Bearer <JWT_Token>.
  4. Context Header Injection: The Gateway validates and decrypts the JWT. It extracts token claims and injects them as raw, trust-verified headers for downstream microservices to consume instantly:
    • X-Milesoft-User-Id: The unique identifier of the authenticated user.
    • X-Milesoft-App-Id: The registered application ID invoking the platform.
    • X-Milesoft-Account-Id: The tenant/subscriber account context under which the request is running.
    • X-Milesoft-User-Roles: A comma-separated list of the user's active authorities (e.g., ROLE_SUPER,ROLE_ADMIN).

Downstream services utilize these headers directly, bypassing the need to re-verify authentication tokens on every internal microservice call.

+--------+            +---------+            +--------------+
| Client |            | Gateway |            | Microservice |
+--------+            +---------+            +--------------+
    |                      |                        |
    | GET /api/v2/user/123 |                        |
    | Auth: Bearer JWT     |                        |
    |--------------------->|                        |
    |                      | [1] Decrypt & Verify   |
    |                      | [2] Inject headers:    |
    |                      |     X-Milesoft-User-Id |
    |                      |     X-Milesoft-App-Id  |
    |                      |     X-Milesoft-Roles   |
    |                      |----------------------->|
    |                      |                        | [3] Run scoped logic
    |                      |                        |     using context headers
    |                      |                        | [4] Return payload
    |                      |<-----------------------|
    |<---------------------|                        |
    |                      |                        |

3.2 Multi-Tenant Data Isolation

Milesoft is built from the ground up to support massive multi-tenant scale. Core isolation is enforced natively inside backend databases (Google Cloud Firestore):

  • No Direct Sharing: Data entities are partitioned implicitly or explicitly by Account ID (X-Milesoft-Account-Id).
  • AssumeAccount Middleware: In Java-based applications, the app-stack library intercepts incoming requests, captures the tenancy headers, and binds them to a thread-local execution context. Database queries automatically append filter clauses matching the thread's Account ID context, making cross-tenant data leaks impossible.

4. Local Integration & SDK Layer

Client backend projects incorporate the platform utilizing a tiered dependency architecture hosted on Google Cloud Artifact Registry.

4.1 Dependency Registry

  • Repository (milesoft-repo): SDK libraries, platform extensions, and open-source packages available to clients and partners.
    • URL: artifactregistry://us-west2-maven.pkg.dev/milesoft-repo/repo-maven

4.2 SDK Packages at a Glance

Developers utilize our pre-built client SDKs to write clean, typesafe integration logic rather than writing raw REST clients.

  • app-stack: The central framework scaffolding. It configures Jackson serializers, exception mappers, security filters, thread-local multi-tenant contexts, and Google Cloud Run diagnostic health checks.
  • accounts-sdk: Programmatic API for logging in users, asserting permissions, and checking user directory states.
  • contacts-sdk: Strongly-typed classes for node/edge management, layout rendering, and graph synchronization.
  • liquid-sdk: Interface for Liquid compiling, rendering PDF templates, and managing template models.
  • notifications-sdk: Simplified, high-level client interfaces to dispatch emails, text alerts, or push notifications without needingTwilio or FCM client details.

5. Development and Release Cycles

When developing client-side applications, the following release strategies apply:

  • The milesoft sdk CLI Commands: Developers do not need to hunt for SDK library version mappings in documentation. Run milesoft sdk list to query active releases from the registry, or run milesoft sdk get <sdk-id> to output the correct Gradle compile dependency string for your project.
  • Stable Version Promotion: Always prioritize pinned release versions (e.g., io.milesoft:liquid-sdk:2.0.0) for production-grade builds to prevent compiler drift and secure repeatable build outputs.