Gateway

@nx/gateway is the platform edge gateway, not an IGNIS microservice. It ships proxy configuration (Traefik v3.6 + a local Nginx route table) and a static Astro + React developer portal (@nx/gateway-portal). It has no database, no domain entities, no Kafka, no migrations — the root package.json carries metadata only.

1. Quick Reference

Property	Value
Package	@nx/gateway
Type	API Gateway (edge proxy + dev route table + portal) — not an IGNIS service
Runtime (prod proxy)	Traefik v3.6 (traefik:v3.6)
Runtime (dev proxy)	Nginx (nginx:1.27-alpine, host networking, Linux-only)
Runtime (portal)	Astro 5 + React 19 + Tailwind 4 (static), served by nginxinc/nginx-unprivileged:1.27-alpine
Traefik entrypoints	web (:80), traefik (:8080 dashboard + Prometheus metrics)
HTTPS entrypoint	None — TLS terminated at edge Nginx, not Traefik
Portal dev port	3003 (astro dev)
Portal container port	8080
DB schema	N/A — no datastore
Snowflake ID	N/A — no ID generation
Domain entities / Kafka	N/A — see Domain Model, API Events
Location	packages/gateway
Owner	Platform / Infra

2. Purpose & Scope

Included	Excluded
Edge routing to backend services (Traefik Docker-label discovery)	TLS termination (edge Nginx owns it)
Resilience: circuit breaker, rate limiting, security headers	Business logic / domain data (services own it)
Observability: Prometheus metrics, JSON access logs, Traefik dashboard	Persistence — no DB, no migrations
Native-dev single-entry route table (local Nginx)	Event streaming — no Kafka producer/consumer
Developer portal: service health + OpenAPI explorer	Auth issuance — identity owns JWT/JWKS

3. Tech Stack

Proxy layer (config-only, no build):

Component	Purpose
Traefik v3.6	Production reverse proxy; Docker + File providers; resilience + metrics
Nginx 1.27-alpine	Local-dev central route table (local/); fronts native 127.0.0.1:31xx services

Portal (@nx/gateway-portal):

Library	Purpose
astro ^5.7	Static-site builder (output: 'static')
react / react-dom ^19.1	Interactive islands (health table, endpoint explorer)
tailwindcss ^4.2	Styling via @tailwindcss/vite
lucide-react	Icons
sonner	Toast notifications
clsx, tailwind-merge	Class composition

The portal has its own bun.lock and dependency tree — not part of the backend build chain. Traefik/Nginx configs require no build step.

4. Project Structure

packages/gateway/
├── config/
│   ├── traefik.yml                 # Traefik static config (entrypoints, providers, log, metrics)
│   └── dynamic/
│       └── middlewares.yml         # Dashboard routers + shared middlewares (file provider)
├── local/
│   ├── docker-compose.yml          # local-nx-gateway (nginx, host networking)
│   └── nginx.conf                  # Central dev route table (/v1/api/<svc>/ + /stream)
├── portal/                         # @nx/gateway-portal — Astro 5 + React 19 + Tailwind 4
│   ├── src/
│   │   ├── components/             # Portal UI (home, services, monitor)
│   │   ├── pages/                  # index.astro
│   │   ├── hooks/                  # use-health-check.ts
│   │   ├── helpers/                # openapi-parser.helper.ts
│   │   ├── interfaces/             # IService, IApp, IEndpoint, ...
│   │   └── constants/              # services.constant.ts, apps.constant.ts
│   ├── astro.config.ts             # dev server :3003, static output
│   ├── nginx.conf                  # Serving config (no-cache HTML, immutable assets)
│   ├── Dockerfile                  # Static build → nginx-unprivileged :8080
│   └── package.json                # @nx/gateway-portal
├── AGENTS.md
└── package.json                    # @nx/gateway (metadata only — no scripts, no deps)

5. Architecture

Full C4 + request-routing flows: see Architecture.

6. Domain Snapshot

N/A — gateway has no datastore and no domain entities. Routing rules and middleware definitions are the only "model"; they live in config, not a database. See Domain Model.

7. Surface Summary

The gateway exposes no REST API of its own — it proxies other services' surfaces. The only gateway-owned endpoints are operational:

Endpoint	Layer	Purpose
/__gateway_health	Local Nginx	Dev gateway liveness probe (returns JSON {status:ok})
/dashboard, /api	Traefik :8080	Traefik dashboard + internal API (basic-auth)
/metrics	Traefik :8080	Prometheus metrics

Async topics: N/A — gateway emits/consumes no Kafka, BullMQ, or WebSocket events. See API Events.

8. Components

Component	Source	Purpose
Traefik static config	config/traefik.yml	Entrypoints, Docker + File providers, JSON logs, Prometheus metrics
Traefik dynamic config	config/dynamic/middlewares.yml	Dashboard routers + shared middlewares (file provider)
Local Nginx route table	local/nginx.conf	Central dev route table for native services
Portal	portal/src/	Static service-catalog SPA (health + OpenAPI explorer)

Detail: see Configuration.

9. Services

N/A — no IGNIS services. The gateway has no TypeScript backend. The portal's logic lives in React hooks/helpers (use-health-check.ts, openapi-parser.helper.ts), not IGNIS BaseService classes.

10. Repositories

N/A — no datastore, no repositories.

11. Entry Points

File	Purpose
config/traefik.yml	Traefik bootstrap (static config)
local/docker-compose.yml	Local dev gateway container (local-nx-gateway)
portal/astro.config.ts	Portal dev server (:3003) + static build
portal/Dockerfile	Portal production image (nginx :8080)

There is no src/index.ts / migrate.ts — gateway is not an IGNIS application.

12. Configuration

Traefik static/dynamic config, local Nginx upstreams, portal env, and the service/apps constant lists: see Configuration.

13. Operations

Deploy of Traefik + portal, observability (metrics on :8080), security (rate limit, circuit breaker), and runbook: see Operations.

14. Related Pages

Concepts

• Architecture
• Domain Model — N/A marker
• Selection Report

Reference

• API Events — N/A marker
• Configuration
• Operations

Features

• Routing
• Middlewares
• Resilience
• Observability

Decisions

• Decisions