Gateway

@nx/gateway là edge gateway của nền tảng, không phải một microservice IGNIS. Nó ship cấu hình proxy (Traefik v3.6 + một bảng route Nginx cục bộ) và một developer portal tĩnh Astro + React (@nx/gateway-portal). Nó không có database, không thực thể domain, không Kafka, không migration — package.json gốc chỉ mang metadata.

1. Tham khảo nhanh

Thuộc tính	Giá trị
Package	@nx/gateway
Type	API Gateway (edge proxy + bảng route dev + portal) — không phải dịch vụ IGNIS
Runtime (prod proxy)	Traefik v3.6 (traefik:v3.6)
Runtime (dev proxy)	Nginx (nginx:1.27-alpine, host networking, chỉ Linux)
Runtime (portal)	Astro 5 + React 19 + Tailwind 4 (tĩnh), phục vụ bởi nginxinc/nginx-unprivileged:1.27-alpine
Traefik entrypoints	web (:80), traefik (:8080 dashboard + Prometheus metrics)
HTTPS entrypoint	Không — TLS được kết thúc tại edge Nginx, không phải Traefik
Portal dev port	3003 (astro dev)
Portal container port	8080
DB schema	N/A — không có datastore
Snowflake ID	N/A — không sinh ID
Thực thể domain / Kafka	N/A — xem Domain Model, API Events
Location	packages/gateway
Owner	Platform / Infra

2. Mục đích & Phạm vi

Bao gồm	Loại trừ
Edge routing tới các dịch vụ backend (Traefik khám phá qua Docker-label)	TLS termination (edge Nginx sở hữu)
Resilience: circuit breaker, rate limiting, security headers	Business logic / dữ liệu domain (dịch vụ sở hữu)
Observability: Prometheus metrics, JSON access logs, Traefik dashboard	Persistence — không DB, không migration
Bảng route một-cổng cho dev native (Nginx cục bộ)	Event streaming — không Kafka producer/consumer
Developer portal: sức khỏe dịch vụ + trình khám phá OpenAPI	Cấp phát auth — identity sở hữu JWT/JWKS

3. Tech Stack

Lớp proxy (chỉ config, không build):

Component	Mục đích
Traefik v3.6	Reverse proxy production; Docker + File provider; resilience + metrics
Nginx 1.27-alpine	Bảng route trung tâm dev cục bộ (local/); đứng trước các dịch vụ native 127.0.0.1:31xx

Portal (@nx/gateway-portal):

Thư viện	Mục đích
astro ^5.7	Trình build static-site (output: 'static')
react / react-dom ^19.1	Island tương tác (bảng sức khỏe, trình khám phá endpoint)
tailwindcss ^4.2	Styling qua @tailwindcss/vite
lucide-react	Icons
sonner	Thông báo toast
clsx, tailwind-merge	Tổ hợp class

Portal có bun.lock và cây phụ thuộc riêng — không thuộc chuỗi build backend. Config Traefik/Nginx không cần bước build.

4. Cấu trúc dự án

packages/gateway/
├── config/
│   ├── traefik.yml                 # Config tĩnh Traefik (entrypoints, providers, log, metrics)
│   └── dynamic/
│       └── middlewares.yml         # Router dashboard + middleware dùng chung (file provider)
├── local/
│   ├── docker-compose.yml          # local-nx-gateway (nginx, host networking)
│   └── nginx.conf                  # Bảng route dev trung tâm (/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, output tĩnh
│   ├── nginx.conf                  # Config phục vụ (HTML no-cache, asset immutable)
│   ├── Dockerfile                  # Build tĩnh → nginx-unprivileged :8080
│   └── package.json                # @nx/gateway-portal
├── AGENTS.md
└── package.json                    # @nx/gateway (chỉ metadata — không script, không deps)

5. Kiến trúc

C4 đầy đủ + luồng request-routing: xem Kiến trúc.

6. Ảnh chụp Domain

N/A — gateway không có datastore và không có thực thể domain. Quy tắc routing và định nghĩa middleware là "model" duy nhất; chúng nằm trong config, không phải database. Xem Domain Model.

7. Tóm tắt Bề mặt

Gateway không phơi bày REST API riêng — nó proxy bề mặt của các dịch vụ khác. Các endpoint duy nhất do gateway sở hữu là vận hành:

Endpoint	Lớp	Mục đích
/__gateway_health	Local Nginx	Liveness probe gateway dev (trả về JSON {status:ok})
/dashboard, /api	Traefik :8080	Traefik dashboard + API nội bộ (basic-auth)
/metrics	Traefik :8080	Prometheus metrics

Async topics: N/A — gateway không phát/tiêu thụ sự kiện Kafka, BullMQ, hay WebSocket. Xem API Events.

8. Components

Component	Nguồn	Mục đích
Config tĩnh Traefik	config/traefik.yml	Entrypoints, Docker + File provider, JSON logs, Prometheus metrics
Config động Traefik	config/dynamic/middlewares.yml	Router dashboard + middleware dùng chung (file provider)
Bảng route Nginx cục bộ	local/nginx.conf	Bảng route dev trung tâm cho dịch vụ native
Portal	portal/src/	SPA service-catalog tĩnh (sức khỏe + trình khám phá OpenAPI)

Chi tiết: xem Cấu hình.

9. Services

N/A — không có dịch vụ IGNIS. Gateway không có backend TypeScript. Logic của portal nằm trong React hooks/helpers (use-health-check.ts, openapi-parser.helper.ts), không phải các lớp IGNIS BaseService.

10. Repositories

N/A — không có datastore, không có repository.

11. Điểm vào

File	Mục đích
config/traefik.yml	Bootstrap Traefik (config tĩnh)
local/docker-compose.yml	Container gateway dev cục bộ (local-nx-gateway)
portal/astro.config.ts	Dev server portal (:3003) + build tĩnh
portal/Dockerfile	Image production portal (nginx :8080)

Không có src/index.ts / migrate.ts — gateway không phải một ứng dụng IGNIS.

12. Cấu hình

Config tĩnh/động Traefik, upstream Nginx cục bộ, env portal, và danh sách hằng số service/apps: xem Cấu hình.

13. Vận hành

Deploy Traefik + portal, observability (metrics trên :8080), bảo mật (rate limit, circuit breaker), và runbook: xem Vận hành.

14. Trang liên quan

Khái niệm

• Kiến trúc
• Domain Model — đánh dấu N/A
• Selection Report

Tham khảo

• API Events — đánh dấu N/A
• Cấu hình
• Vận hành

Tính năng

• Routing
• Middlewares
• Resilience
• Observability

Quyết định

• Quyết định