Skip to content

Reference architecture ​

Gatelin is the entry point of a three-service stack. It authenticates callers and proxies to Megadex (users) and Foxnox (credentials), which in turn call each other directly.

┌─────────────────────────────────────────────────┐
│                  Reverse Proxy                   │
│                    (Traefik)                     │
│              http://your-domain.com              │
└────────────┬─────────────────────┬───────────────┘
             │                     │
   ┌─────────▼─────────┐  ┌────────▼──────────┐
   │   Admin Panels    │  │      Gatelin      │
   │     (Angular)     │  │   BFF  /api/*     │
   └───────────────────┘  └────────┬──────────┘
                                   │  internal network only
            ┌──────────────────────┼──────────────────────┐
            │                      │                      │
   ┌────────▼──────────┐           │             ┌────────▼──────────┐
   │      Megadex      │◄──────────┴─────────────┤      Foxnox       │
   │     /megadex      │     USER_SEARCH_URL     │  /foxnox  /web    │
   │     (Node.js)     ├────────────────────────►│     (Node.js)     │
   └────────┬──────────┘     PWD_CREATE_URL      └────────┬──────────┘
            │                                             │
   ┌────────▼──────────┐                         ┌────────▼──────────┐
   │    PostgreSQL     │                         │    PostgreSQL     │
   │   (megadex DB)    │                         │   (foxnox DB)     │
   └───────────────────┘                         └───────────────────┘

Each service owns its own database and knows the others only by HTTP contract.

ServiceOwnsNever does
GatelinSessions, JWTs, routes, roles, permissions, CORSStore password hashes or user profiles
MegadexUsers, role assignment, social links, preferences, lookupsStore credentials or issue sessions
FoxnoxPassword hashes, 2FA, tokens, trusted devices, workflow pagesMint JWTs or store user profiles

Users are identified by email at the edge and by numeric userId everywhere else. Megadex is the only place that translates one into the other.

Sign-in ​

Account creation ​

Password recovery ​

Who calls whom ​

CallerCalleeVariablePurpose
GatelinMegadexUSER_SEARCH_URLResolve email to userId at login
GatelinFoxnoxPWD_CHECK_URLVerify the password
GatelinFoxnoxPWD_CHALLENGES_URL, PWD_TRUSTED_DEVICES_URL, PWD_LOGIN_TICKET_URLMid-login 2FA and expired-password steps
FoxnoxMegadexUSER_SEARCH_URLResolve email in recovery, unlock and 2FA recovery
MegadexFoxnoxPWD_CREATE_URLCreate a password on user creation, archive it on user archival
GatelinMegadex, FoxnoxRoute and permission seedsProxy admin and self-service traffic with consumer and ACL headers

Boundaries to keep in mind ​

  • Trust: Megadex and Foxnox trust Gatelin's x-consumer-* and x-acl-* headers, so only Gatelin (and each other) may reach their ports. Neither should have a public router.
  • Sessions: Gatelin owns session state. Role changes or archival in Megadex take effect only when the access token expires or refresh fails. Nothing pushes a revocation.
  • Coupling: creating a user in Megadex fails, and rolls back by archiving, if Foxnox is down. Gatelin sign-in fails if Megadex or Foxnox is unreachable.
  • Optional: each service works with other implementations of the same HTTP contract. A custom BFF, user service or credential store can replace any one of the three.

Published and maintained by ALTEN