huybaoo1/distributed-system-api-gateway-dang-phan-bao-huy

1. Overall shape

This repo is not a single app but a small distributed testbed for an API gateway. The main runtime path is: client traffic goes to a Spring Boot gateway, the gateway rate-limits and measures latency, then proxies allowed requests to a mock backend. Redis is the shared state store for the distributed rate limiters.

2. Gateway service boundary

api-gateway is the core component. It exposes /api/v1/** as the public request surface and has internal endpoints for metrics and system inspection. The gateway is also where the architecture variants live: different rate-limiting strategies, different Redis fault policies, and the latency headers used for experiments.

3. Request flow through the gateway

Incoming requests first pass through a rate-limiting filter, then the gateway forwards them to the backend service. On the response path, it adds timing and quota headers such as rate-limit latency, backend latency, total gateway latency, remaining quota, reset time, and Retry-After for rejections. This makes the gateway both a proxy and a measurement instrument.

4. Rate limiting subsystem

The repo contains four limiter modes:

- redis-sliding-window

- redis-fixed-window

- redis-token-bucket

- in-memory

The Redis-backed strategies use Redis as the authoritative state store and differ only in how quota state is modeled. The in-memory mode is local to one gateway instance and serves as a baseline or fallback comparison point.

5. Redis fault handling boundary

Redis is treated as a potentially failing dependency. The gateway supports three policies when Redis is unreachable:

- fail-closed

- fail-open

- local-fallback

This is an important architectural boundary because availability and correctness trade off differently depending on policy. The “local fallback” path shifts decision-making from distributed state to per-instance state during failure.

6. Latency and observability path

The gateway has dedicated controllers and services for reporting internal latency snapshots and formatting metrics. The repository is built to separate client-observed latency from gateway processing, backend delay, and rate-limiter overhead. That separation is central to the experiment design and is exposed through headers plus internal report endpoints.

7. Backend simulation

mock-backend-service/mock-backend-service is a minimal Spring Boot backend that simulates downstream latency through a delayMs parameter. It exists to isolate gateway behavior from real application complexity. This backend is the target of the gateway proxy and is the source of controlled backend delay in experiments.

8. Runtime topology and deployment

The repo includes Dockerfiles and docker-compose.yml for running the full stack locally: gateway(s), mock backend, Redis, and Redis Commander. There is also a scaled setup using Nginx as a load balancer in docker-compose.scaled.yml and nginx/gateway-scaled.conf, which models a multi-instance gateway deployment behind a shared entrypoint.

9. Experiment and analysis tooling

The Python scripts are an external experiment harness rather than part of the gateway runtime. They drive benchmark traffic, generate scenario matrices, inject Redis failures, and produce reports/plots. The reports/ directory stores manifests and trial outputs, while plot_latency_report.py and the dashboard consume those artifacts for analysis.

10. Test and verification structure

The gateway has unit tests for the controller, filter, and service logic, plus Redis integration tests using Testcontainers. The backend has a basic Spring context test. This splits verification into fast local behavior checks and environment-backed checks that validate Redis-dependent strategies.

11. User-facing analysis UI

ui/latency-dashboard is a static dashboard that reads experiment CSV/manifest outputs and visualizes latency comparisons. It is not part of the request path; it is a post-processing view for the artifact pipeline.

12. Architecture diagram cues

A correct diagram should show:

- clients hitting one of several gateway entrypoints

- gateway internals split into request filtering, rate-limit decisioning, proxying, and metrics

- Redis as a shared distributed dependency for most strategies

- mock backend as the downstream target

- experiment scripts and report artifacts as an offline analysis pipeline

- optional Nginx/load-balanced gateway deployment for scale-out scenarios