---
title: "Architecture Diagram"
slug: architecture-diagram
section: Overview & Architecture
status: stable
description: "Complete solution blueprint — all systems, integrations, and data flows in a single view"
last-updated: 2026-10-07
---

# Architecture Diagram

Complete solution blueprint — all systems, integrations, and data flows in a single view

## Solution Overview

> **Globus decides. Portals reflect.**
>
> The entire ecosystem follows one principle: Globus is the system of record. External portals capture data and present decisions — they never make authoritative decisions independently. All business logic, eligibility rules, compliance gates, and approval workflows live in Globus.

The architecture spans four tiers: External Entry Points (how data enters the system), the Globus Core Stack (10 capability layers processing all business logic), Integration Systems (external services Globus orchestrates), and Operational Outputs (what the system produces). Each click navigates to the detailed documentation.

[](/arch_final_clean.png)

Click image to view full size. Last updated: 2026-06-27 (Post-Audit)

External Entry Points

Globus Core — Capability Layers

Integration Systems

Operational Outputs

## External Entry Points

Four external systems feed data into Globus. Each has a defined API contract with specific endpoints, authentication requirements, and event flows.

| Entry Point | Type | Primary Endpoint | Auth | Key Event |
| --- | --- | --- | --- | --- |
| HubSpot (via n8n) | Workflow trigger (push) | POST /api/integrations/onboarding/provision | x-api-key (integrations.onboarding scope) | applicant provisioned in Globus + invite token |
| Applicant Portal | API (bidirectional) | /api/portal/* | integrations.portal (X-API-Key) | travel_request.*, step_completed |
| Partner Portal | API (bidirectional) | /api/partner/* | portal.partner_proxy | nomination.submitted, reservation.created |
| Host Portal | API (bidirectional) | /api/partner/host/* | portal.host_proxy | host.arrival.create, host.reservation.hire |

> **Globus-First Intake (as-built)**
>
> For applicant onboarding, Globus creates the applicant: n8n calls POST /api/integrations/onboarding/provision on the Hub, which mints the applicant, application and portal invite token in one call. The full as-built intake flow — provision, invite delivery, token preview, activation and the first-login agreement gate — is documented in Direct vs Partner Entry. Implementation ground truth: PPPToo Architecture.

## Globus Core Stack

Globus is organized into 10 capability layers (L0–L9). Lower layers must stabilize before upper layers build on them. The Phase A exit criterion is a full operational run of the Camp Counselor program inside Globus.

| Layer | Name | Responsibility | Project | Status |
| --- | --- | --- | --- | --- |

See Globus Capability Layers for detailed technical specifications of each layer.

## Integration Systems

Globus orchestrates five external systems. Each integration follows a defined contract with clear ownership boundaries.

#### Private OCR (GCP Document AI)

Passport OCR inside Google Cloud over a private network path — replaces the OpenAI GPT-4o public OCR call.

ID_PROOFING_PROCESSOR in dedicated globus-ocr project / Private Service Connect — no public OCR API / NetworkPolicy: only ocr-service-caller pods egress / Cross-project Workload Identity (no key files) / CMEK globus-docai-cmek + us residency

Project: P8 · See Private OCR

#### SEVIS & Compliance Gateway

U.S. government integration for J-1/J-2 visa compliance.

DS-2019 issuance & amendments / SEVIS status sync (active, terminated, no-show) / Check-in compliance tracking / Site visit management / SEVIS certificate generation

Project: P10 · See Capability Layers

#### NetSuite (Finance ERP)

Financial system of record — NetSuite-first approach.

Customer sync at first payment / Fee catalog management / Invoice generation & pulling / Payment status tracking / Multi-currency support

Project: P9 · See Finance & NetSuite

#### Keycloak (Identity Provider)

Production authentication — replaces Replit Auth prototype.

OIDC + Client Credentials flow / Realm-per-brand multi-tenancy / Social login brokering (Google, Facebook) / Keycloak = identity, Globus = authorization / API contract unchanged during migration

Project: P1 · See Integration Contract

#### n8n (Automation Engine)

Workflow automation — the ecosystem's nervous system.

Scheduled eligibility rechecks / Compliance deadline monitoring / External system sync orchestration / Error handling & retry cascades / Data transformation pipelines

Project: P8 · See n8n Automation Layer

## Operational Outputs

Five operational domains emerge from the Globus core and its integrations. These represent the business value the system delivers.

| Domain | Project | Key Capabilities | Dependencies |
| --- | --- | --- | --- |
| On-Program Lifecycle | P23–P30 (8 projects) | Check-ins, Program Extensions, Program Renewals, travel approvals, terminations | P5, P10, P11 |
| Reporting & Insights | P15 | Executive dashboards, compliance reports, data exports | All projects |
| Housing & Accommodation | P14 | Housing assignments, inspections, host family matching | P4, P5 |
| Quota & Capacity | — | Quota allocation, fill rate tracking, workforce intelligence | P1, P5 |
| Partner Management | P12 | Partner models, agreements, performance scoring | P1 |

## Coordination & Tracking

Two systems sit outside the core architecture but coordinate the ecosystem's development and alignment.

#### MCP Coordination Server

Ecosystem-wide state synchronization. Ensures all portals operate on current architecture.

3 portals registered (Partner, GLOBUS Hub, Governance Hub) / Heartbeat monitoring (current/stale detection) / Sync status with change summaries / Architecture change propagation

Endpoint: mcp.allianceabroad.com/mcp · Portal ID: 3

#### Asana Portfolio

Project tracking across the full development scope.

117 tracked Asana projects across 6 delivery goals / Live task counts on the Delivery Overview page / Dependency-ordered build sequence / Live portfolio dashboard on Roadmap page

View Delivery Overview →

## Data Flow Paths

Key data flows across the ecosystem. Each arrow represents a defined contract with specific payload and authentication.

| Flow | From | To | Mechanism | Key Payload |
| --- | --- | --- | --- | --- |
| Applicant Onboarding (as-built) | HubSpot via n8n | Globus → email invite → Applicant Portal | POST /api/integrations/onboarding/provision → invite_url | contact + program → applicant, application, invite token |
| Travel Request | Applicant Portal | Globus | POST /api/travel-requests/receive | 14-field push payload |
| Travel Decision | Globus | Applicant Portal | Webhook (HMAC) | travel_request.approved/rejected |
| Position Reservation | Partner Portal | Globus | POST /api/partner/reservations | applicant_id, reservation details |
| Placement Confirmation | Globus | Host Portal | Webhook | applicant.placement_confirmed |
| SEVIS Sync | Globus | SEVIS | API (batch) | DS-2019, status updates, amendments |
| Invoice Sync | Globus | NetSuite | REST API | Customer, fee events, payment status |
| Arrival Confirmation | Host Portal | Globus | POST /api/partner/host/arrivals (PATCH /:id to update) | Arrival date, housing status |

See Data Flow Between Systems for the full data flow documentation.

## Dual Authentication

Globus implements a dual authentication pattern supporting both browser-based staff users and external system integrations.

#### Session Cookies

Browser-based staff user authentication.

7-day TTL with rolling expiry / PostgreSQL session store (connect-pg-simple) / Session token fallback via Authorization: Bearer header / Secure, httpOnly, sameSite cookie attributes

#### API Keys

External integration authentication.

X-API-Key header for portal \u2192 Globus auth / SHA-256 hashed storage (never stored in plain text) / Scope-enforced access control per key / Per-portal type scoping (applicant, host, partner)

> **MFA Support**
>
> Multi-factor authentication is supported via TOTP (Time-based One-Time Password) with configurable per-role enforcement. MFA can be required for sensitive roles such as super admins and compliance officers.

## Standardized API Contract

All Globus API endpoints follow a standardized contract ensuring consistency, traceability, and safe retries across the platform.

## Dual Event Outbox

Globus uses two separate event outbox tables to cleanly separate external integration events from internal domain events.

#### ops_events (External)

Events for n8n webhooks and external integrations.

Pushed to n8n webhook URLs immediately on emit / Best-effort delivery with configurable retries / Dead-letter queue for failed deliveries / Admin dashboard for monitoring delivery health / Enriched payloads with applicant/program context

#### event_outbox (Internal)

Domain events for cross-context consistency.

Internal domain events within Globus bounded contexts / correlationId for grouping related events / causationId for event chain tracing / Supports aggregate-level event sourcing patterns / Used for cross-module communication without direct imports

> **Why Two Outboxes?**
>
> External events (ops_events) are optimized for webhook delivery with retry semantics. Internal events (event_outbox) are optimized for domain consistency with correlation/causation chains. Merging them would compromise both use cases.

## Authentication Architecture

Authentication follows a phased migration path. The API contract remains stable across both phases.

Retired — Prototype Era

#### Replit Auth + API Key

Replit Auth handled identity during prototyping (retired — applicant portal now uses same-origin Keycloak /sign-in) / X-API-Key header for portal→Globus auth (still current) / API key scoped per portal type / Do not build new logins against Replit Auth

Target — Production

#### Keycloak OIDC

Keycloak handles identity (OIDC + social login) / Client Credentials for service-to-service auth / Realm-per-brand multi-tenancy / Globus still owns authorization (RBAC)

> **Key Separation**
>
> Keycloak = Identity (who are you?) · Globus = Authorization (what can you do?). Social login (Google/Facebook) is a target-state option via Keycloak identity brokering — not shipped today — and would not change the Globus API contract, the HubSpot webhook payload, or the structure of the Globus-emitted applicant.created event.

## CI/CD & Deployment

The build and deployment pipeline runs on Google Cloud Build with quality gates enforced on every commit. Cloud Build provides native access to GCS, Cloud Run, and Secret Manager without cross-cloud credential management.

### Cloud Build Pipeline

Active Standard

#### GitHub Actions + GKE

Native GCP integration (no cross-cloud credentials) / GitHub Actions workflows deploy feature/* branches to a dev pool slot, release/* branches to a QA pool slot, and main to production by blue-green cutover (sandbox branching model since 2026-10-06) / Automatic GKE rollouts via kubectl apply / Secret Manager integration for env vars / Built-in container registry (Artifact Registry) / Build steps run in isolated containers

> **Quality Gates**
>
> Every commit must pass the full quality gate pipeline before deployment: Type Check \u2192 Lint \u2192 Test (7,711+ tests) \u2192 Docker Build. No step can be skipped or bypassed.

### Deployment Infrastructure

#### Runtime Environment

Docker containers on GKE (globus-app deployment; k8s/development, k8s/qa, k8s/prod) / Horizontal pod autoscaling (HPA) / Rolling updates gated by kubectl rollout status / Secret Manager for environment variables / Artifact Registry for container images

#### Session Management

PostgreSQL-backed sessions via connect-pg-simple / 7-day TTL with rolling expiry window / Sessions persist across deployments and container restarts / No in-memory session state (stateless containers) / Session ID usable as Bearer token for API clients

## DDD Module Decomposition

Status: this is a conceptual decomposition, not the physical code layout. In BackOfficePrototype, server/ is organised as flat routes/, services/, storage/ and lib/ directories and shared/models/ is split by context; there are no per-module directories, no shared/kernel package, and tables are not module-prefixed (for example applicant_documents).

The Globus codebase follows a Domain-Driven Design (DDD) module structure. Each capability layer maps to a bounded context with clear ownership, internal models, and a public API surface. This decomposition ensures that changes in one domain do not cascade unexpectedly to others.

| Module | Bounded Context | Aggregates | Layer |
| --- | --- | --- | --- |
| identity | Identity & Access | User, Role, Permission, Session | L0 |
| programs | Program Catalog | Program, ProgramRule, VisaCategory | L1 |
| seasons | Operational Cohorts | Season, Intake, Capacity, Lifecycle | L2 |
| applicants | Participant Records | Applicant, Application, Document, J2Dependent | L3 |
| workflows | Workflow State | Journey, Step, StepCompletion, Evidence | L4 |
| rules | Business Rules | RuleSet, RuleEvaluation, ComplianceGate | L5 |
| job-orders | Job Orders & Capacity Management | JobOrder, JobOrderRequirement, CapacityCounter | L6 |
| matching | Matching & Reservations | Match, Reservation, Placement | L7 |
| comms | Communications | Template, Notification, DeliveryRecord, EventOutbox | L8 |
| automation | Automation & Integrations | WorkflowTrigger, ExternalSync, WebhookSubscription, RetryPolicy | L9 |

Each module has its own directory with routes, services, repositories, and domain models / Cross-module communication uses domain events (via the Event Outbox), not direct imports / Shared kernel types (IDs, enums, value objects) live in a shared/kernel package / Database tables are prefixed by module (e.g., seasons_intake, applicants_documents) / Module boundaries align with the 10-layer capability stack — one module per layer

> **DDD Aligns with Capability Layers**
>
> The DDD module structure is not an accident — it directly mirrors the 10-layer capability stack. This means a developer working on “seasons” operates within a single module that maps to Layer 2, with clear boundaries and no need to navigate unrelated domain code.

## Build Status Summary

Current build phase across all tracked projects. The architecture follows an "Architecture First, Not UI First" philosophy — lower layers stabilize before upper layers build.

See Delivery Overview for the live Asana portfolio dashboard and detailed project breakdown.