{"id":48680708,"url":"https://github.com/DevLink-Tech-Academy/waterwall-api-gateway","last_synced_at":"2026-04-26T20:00:42.074Z","repository":{"id":347871713,"uuid":"1195522100","full_name":"DevLink-Tech-Academy/waterwall-api-gateway","owner":"DevLink-Tech-Academy","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-09T23:21:22.000Z","size":1524,"stargazers_count":46,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-10T01:24:25.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DevLink-Tech-Academy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"open_collective":null,"ko_fi":null,"buy_me_a_coffee":null,"custom":null}},"created_at":"2026-03-29T19:07:33.000Z","updated_at":"2026-04-10T00:22:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DevLink-Tech-Academy/waterwall-api-gateway","commit_stats":null,"previous_names":["devlink-tech-academy/waterwall-api-gateway"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DevLink-Tech-Academy/waterwall-api-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevLink-Tech-Academy%2Fwaterwall-api-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevLink-Tech-Academy%2Fwaterwall-api-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevLink-Tech-Academy%2Fwaterwall-api-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevLink-Tech-Academy%2Fwaterwall-api-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DevLink-Tech-Academy","download_url":"https://codeload.github.com/DevLink-Tech-Academy/waterwall-api-gateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevLink-Tech-Academy%2Fwaterwall-api-gateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32310804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T19:15:34.056Z","status":"ssl_error","status_checked_at":"2026-04-26T19:15:15.467Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-11T01:00:36.055Z","updated_at":"2026-04-26T20:00:42.067Z","avatar_url":"https://github.com/DevLink-Tech-Academy.png","language":"Java","funding_links":[],"categories":["API网关"],"sub_categories":["Spring Cloud框架"],"readme":"# Waterwall\n\n\u003e **The open-source API gateway platform that publishes, secures, monitors, and monetizes APIs — built on Java 21 virtual threads, deployable in 60 seconds.**\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Java](https://img.shields.io/badge/Java-21-orange.svg)](https://openjdk.org/projects/jdk/21/)\n[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.4-6DB33F.svg)](https://spring.io/projects/spring-boot)\n[![Next.js](https://img.shields.io/badge/Next.js-14-black.svg)](https://nextjs.org/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n[![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-2.1-purple.svg)](CODE_OF_CONDUCT.md)\n\nWaterwall is a **full API lifecycle management platform** — not just a proxy. It ships with an admin portal, a developer portal, real-time analytics, pricing plans, billing, and a high-performance request runtime. Think WSO2 API Manager or Kong Enterprise, but open source, Java 21-native, and deployable on a single machine.\n\n## ⚡ Performance\n\nSingle-machine benchmark — all 7 services, PostgreSQL, and RabbitMQ on one box (Windows 11, AMD Ryzen 9 7945HX, 32 GB RAM), measured with [Vegeta](https://github.com/tsenart/vegeta):\n\n| Rate | Success | p50 | p95 | p99 |\n|---:|:---:|---:|---:|---:|\n| **1,000 rps** | 100% | 1.5 ms | 8.0 ms | 20.8 ms |\n| **2,000 rps** | 100% | 1.3 ms | 8.0 ms | 20.1 ms |\n| **3,000 rps** | 100% | 3.5 ms | 22.0 ms | 34.6 ms |\n| **4,000 rps** | 100% | 8.5 ms | 30.5 ms | 65.3 ms |\n\n100% success rate up to 4,000 rps with sub-10ms median latency — on a laptop. See the full table and optimization notes in the [Performance section](#performance).\n\n## Why Waterwall?\n\n|  | Waterwall | Kong OSS | WSO2 APIM | Gravitee CE | Tyk OSS |\n|---|:---:|:---:|:---:|:---:|:---:|\n| Admin portal UI | ✅ | Enterprise only | ✅ | ✅ | Dashboard is paid |\n| Developer portal UI | ✅ | Enterprise only | ✅ | ✅ | Paid |\n| Built-in monetization \u0026 billing | ✅ | ❌ | ✅ | Enterprise only | ❌ |\n| Real-time analytics + SLA monitoring | ✅ | Enterprise only | ✅ | ✅ | Enterprise only |\n| Java 21 + virtual threads (blocking code, no reactive) | ✅ | N/A (Lua/Go) | ❌ | ❌ | N/A (Go) |\n| One-command install on a blank machine | ✅ | ✅ | ❌ | ❌ | ✅ |\n| Fully open source (Apache 2.0) | ✅ | Partial | Partial | Partial | Partial |\n\n\u003e **Data plane:** Waterwall's `gateway-runtime` is a custom reverse proxy built on Spring Boot + Tomcat with Java 21 virtual threads and Apache HttpClient 5 connection pooling — no Spring Cloud Gateway, no Netty WebFlux. Owning the hot path is what makes optimizations like the lock-free circuit breaker, async access logging, and the virtual-thread pinning fix possible. A separate Netty port on 9090 handles gRPC.\n\n## Quickstart (60 seconds)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DevLink-Tech-Academy/waterwall-api-gateway/main/setup.sh -o setup.sh\nsudo bash setup.sh\n```\n\nThen open **http://localhost:3001** (admin) or **http://localhost:3000** (developer portal). Default login: `admin@gateway.local` / `changeme`. Full install options in [Getting Started](#getting-started).\n\n---\n\n## Features\n\n### API Lifecycle Management\n- Create, version, publish, deprecate, and retire APIs\n- API governance with linting and OpenAPI spec validation\n- SDK generation for multiple languages\n- Try-It console for interactive API testing\n\n### Security\n- Multiple authentication types: JWT, API Key, Basic Auth, mTLS, OAuth2\n- WAF rules, IP filtering, and geo-blocking\n- Role-based access control (RBAC)\n\n### Traffic Control\n- Rate limiting with token bucket, sliding window, and strict DB-backed strategies\n- Circuit breaker for upstream fault tolerance\n- Request proxying with distributed tracing\n\n### Analytics and Monitoring\n- Real-time dashboards with SSE streaming\n- SLA monitoring with automated breach detection\n- Custom report builder with CSV export\n- Alerting via email, webhook, and Slack\n\n### Monetization\n- Pricing plans (Free, Flat Rate, Pay-per-Use, Tiered, Freemium) and subscription management\n- Multi-provider payments: Paystack, Stripe, Flutterwave (admin-configurable)\n- Wallet system with pay-as-you-go billing and auto top-up\n- Double-entry accounting ledger with automated invoicing and dunning\n\n### Notifications\n- Asynchronous event processing via RabbitMQ\n- Email, webhook, and Slack delivery channels\n\n---\n\n## Architecture\n\n### Platform Overview\n\n![Platform Overview Architecture](https://raw.githubusercontent.com/DevLink-Tech-Academy/waterwall-api-gateway/main/architecture/platform-overview.svg)\n\n### Identity Service\n\n![Identity Service Architecture](https://raw.githubusercontent.com/DevLink-Tech-Academy/waterwall-api-gateway/main/architecture/02-identity-service-detail.svg)\n\n### API Protection \u0026 Auth Flows\n\n![API Protection and Authentication Flows](https://raw.githubusercontent.com/DevLink-Tech-Academy/waterwall-api-gateway/main/architecture/03-api-protection-auth-flows.svg)\n\n### Versioning \u0026 Environment Flow\n\n![API Versioning and Environment Promotion](https://raw.githubusercontent.com/DevLink-Tech-Academy/waterwall-api-gateway/main/architecture/04-versioning-environment-flow.svg)\n\n\u003e Open [`architecture/architecture-diagrams.html`](architecture/architecture-diagrams.html) locally in a browser for an interactive view with navigation.\n\n### Services\n\n| Service | Port | Description |\n|---|---|---|\n| **gateway-runtime** | 8080 | Request proxy, auth enforcement, rate limiting, WAF, circuit breaker, distributed tracing |\n| **identity-service** | 8081 | User registration/login, JWT/OAuth2 tokens, RBAC, API key management |\n| **management-api** | 8082 | API lifecycle (CRUD, versioning, publish), subscriptions, pricing plans, SDK generation, governance |\n| **analytics-service** | 8083 | Real-time dashboards, SLA monitoring, custom report builder, SSE streaming, alerting |\n| **notification-service** | 8084 | Email, webhook, Slack notifications via RabbitMQ event processing |\n| **gateway-portal** | 3000 | Developer portal — API catalog, Try-It console, subscriptions, billing, docs |\n| **gateway-admin** | 3001 | Admin portal — API management, analytics, monetization, SLA, user management |\n\n### Shared Libraries\n\n| Module | Purpose |\n|---|---|\n| `common-dto` | Shared DTOs, global exception handler, API error responses |\n| `common-logging` | Centralized logging, trace ID propagation |\n| `common-events` | RabbitMQ event definitions and config |\n| `common-cache` | Two-tier caching (Caffeine L1 + RabbitMQ invalidation) |\n| `common-auth` | JWT authentication filter, shared security utilities |\n\n### API Versioning and Governance\n\nWaterwall supports full API version lifecycle with maker-checker approval:\n\n```\nDRAFT ──\u003e IN_REVIEW ──\u003e PUBLISHED ──\u003e DEPRECATED ──\u003e RETIRED\n```\n\n- **Multi-level approval** based on API sensitivity (LOW → 1 level, CRITICAL → 3 levels + cooldown)\n- **Environment-scoped deployments** (DEV, UAT, STAGING, PROD) with per-environment auth enforcement\n- **Environment-scoped API keys and subscriptions** — cross-environment usage is rejected\n\nSee [`architecture/04-versioning-environment-flow.md`](architecture/04-versioning-environment-flow.md) for the full data model and flow diagrams.\n\n### Authentication Flows\n\nThe gateway supports four authentication types, enforced at the runtime proxy layer:\n\n| Auth Type | Header | Use Case |\n|---|---|---|\n| **JWT Bearer** | `Authorization: Bearer \u003ctoken\u003e` | Web/mobile apps, SSO |\n| **API Key** | `X-API-Key: \u003ckey\u003e` | Server-to-server, IoT |\n| **Basic Auth** | `Authorization: Basic \u003cb64\u003e` | Legacy integrations |\n| **mTLS** | Client certificate | High-security B2B |\n\n### Database Schema\n\nPostgreSQL with four schemas, managed by Liquibase migrations:\n\n| Schema | Tables | Purpose |\n|---|---|---|\n| `identity` | users, roles, permissions, sessions, api_keys | Authentication and authorization |\n| `gateway` | apis, routes, plans, subscriptions, applications, rate_limits | API lifecycle and traffic management |\n| `analytics` | request_logs, metrics_1m/1h/1d, alert_rules, sla_configs | Observability and reporting |\n| `notification` | templates, channels, delivery_log | Notification management |\n\n---\n\n## Getting Started\n\nThere are four ways to run Waterwall, from simplest to most flexible.\n\n### Option 1: Pre-built Release (recommended)\n\nDownloads a pre-built release from GitHub — no compilation needed. All services are managed by [PM2](https://pm2.keymetrics.io/) for auto-restart and boot persistence.\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DevLink-Tech-Academy/waterwall-api-gateway/main/setup.sh -o setup.sh\nchmod +x setup.sh\nsudo bash setup.sh\n```\n\nThe script will prompt for your server's IP or domain name so browsers can reach the APIs.\n\nTo skip the prompt:\n\n```bash\nsudo bash setup.sh --host 203.0.113.10\nsudo bash setup.sh --host api.example.com\nsudo bash setup.sh --version v1.0.0 --host api.example.com\n```\n\nThe script will:\n\n1. Detect your OS and install missing prerequisites (Java 21, Node.js, Docker)\n2. Download and extract the latest release from GitHub Releases\n3. Start PostgreSQL and RabbitMQ via Docker Compose\n4. Start all 7 services with PM2 and print access URLs\n\n**Prerequisites installed automatically:** Java 21, Node.js 20, Docker, PM2. No Maven or build tools needed.\n\nAfter the initial setup, use these PM2 commands:\n\n```bash\nsudo pm2 status                  # view all services\nsudo pm2 logs \u003cservice-name\u003e     # tail logs\nsudo pm2 restart all             # restart everything\nsudo pm2 stop all                # stop everything\nsudo pm2 monit                   # real-time monitoring dashboard\n```\n\nTo clean up and start fresh:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DevLink-Tech-Academy/waterwall-api-gateway/main/cleanup.sh -o cleanup.sh\nsudo bash cleanup.sh --all       # stop services, remove containers, wipe data\nsudo bash setup.sh               # fresh install\n```\n\n### Option 2: Build from Source\n\nFor contributors or custom builds. Clones the repo and compiles everything locally.\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DevLink-Tech-Academy/waterwall-api-gateway/main/setup.sh -o setup.sh\nchmod +x setup.sh\nsudo bash setup.sh --build-from-source\n```\n\nOr from an existing clone:\n\n```bash\nsudo bash setup.sh --no-clone\n```\n\n**Additional prerequisites:** Git, Maven 3.9+\n\n\u003e On Linux/macOS, all prerequisites are installed automatically. On Windows, the script prints download links for any missing tools.\n\n### Option 3: Docker Compose (all-in-Docker)\n\nRuns everything in containers. Only requires Docker.\n\n```bash\ngit clone https://github.com/DevLink-Tech-Academy/waterwall-api-gateway.git\ncd waterwall-api-gateway/deploy/docker\ndocker compose up -d\n```\n\nThis builds and starts **9 containers**: PostgreSQL, RabbitMQ, 5 backend services, and 2 frontend portals. The first build takes a few minutes (Maven + npm dependencies are cached for subsequent builds).\n\nTo stop:\n\n```bash\ndocker compose down        # Stop containers (keep data)\ndocker compose down -v     # Stop containers and delete all data\n```\n\n### Option 4: Manual Setup (services run locally)\n\nFor contributors who want to run services individually with hot reload.\n\n**Prerequisites:** Java 21, Maven 3.9+, Node.js 20+, npm 10+, PostgreSQL 16, RabbitMQ 3.13+\n\n#### Step 1: Start infrastructure\n\nUse Docker for just PostgreSQL and RabbitMQ:\n\n```bash\ncd deploy/docker\ndocker compose up -d postgres rabbitmq\n```\n\nOr if running them natively, create the database and schemas:\n\n```sql\nCREATE DATABASE gateway;\n\\c gateway\nCREATE SCHEMA IF NOT EXISTS identity;\nCREATE SCHEMA IF NOT EXISTS gateway;\nCREATE SCHEMA IF NOT EXISTS analytics;\nCREATE SCHEMA IF NOT EXISTS audit;\nCREATE SCHEMA IF NOT EXISTS notification;\n```\n\nAnd create the RabbitMQ virtual host:\n\n```bash\nrabbitmqctl add_vhost /cem\nrabbitmqctl set_permissions -p /cem guest \".*\" \".*\" \".*\"\n```\n\n#### Step 2: Build the backend\n\n```bash\nmvn clean install -DskipTests\n```\n\n#### Step 3: Start backend services\n\nServices must start in order — identity-service first.\n\n**Start all at once (Windows):**\n\n```cmd\nstart-all.bat\n```\n\n**Start individually** (open a separate terminal for each):\n\n```bash\n# 1. Identity Service (start first, wait for it to be ready)\njava -jar identity-service/target/identity-service-1.0.0-SNAPSHOT.jar\n\n# 2. Management API\njava -jar management-api/target/management-api-1.0.0-SNAPSHOT.jar\n\n# 3. Gateway Runtime\njava -jar gateway-runtime/target/gateway-runtime-1.0.0-SNAPSHOT.jar\n\n# 4. Analytics Service\njava -jar analytics-service/target/analytics-service-1.0.0-SNAPSHOT.jar\n\n# 5. Notification Service\njava -jar notification-service/target/notification-service-1.0.0-SNAPSHOT.jar\n```\n\nVerify all services are healthy:\n\n```bash\ncurl http://localhost:8081/actuator/health/liveness   # identity-service\ncurl http://localhost:8082/actuator/health/liveness   # management-api\ncurl http://localhost:8080/actuator/health/liveness   # gateway-runtime\ncurl http://localhost:8083/actuator/health/liveness   # analytics-service\ncurl http://localhost:8084/actuator/health/liveness   # notification-service\n```\n\n#### Step 4: Start the frontends\n\n```bash\nnpm install\n```\n\n**Development mode** (hot reload):\n\n```bash\nnpm run dev:portal   # Developer portal on http://localhost:3000\nnpm run dev:admin    # Admin portal on http://localhost:3001\n```\n\n**Production mode:**\n\n```bash\nnpm run build:all\ncd gateway-portal \u0026\u0026 npx next start -p 3000 \u0026\ncd gateway-admin \u0026\u0026 npx next start -p 3001 \u0026\n```\n\n---\n\n## Access the Platform\n\n| Service | URL | Description |\n|---|---|---|\n| Developer Portal | http://localhost:3000 | API catalog, subscriptions, billing, docs |\n| Admin Portal | http://localhost:3001 | API management, analytics, monetization |\n| Gateway Runtime | http://localhost:8080 | API proxy endpoint |\n| Identity Service | http://localhost:8081 | Auth, users, API keys |\n| Management API | http://localhost:8082 | API lifecycle, subscriptions, plans |\n| Analytics Service | http://localhost:8083 | Dashboards, reports, alerting |\n| Notification Service | http://localhost:8084 | Email, webhook, Slack notifications |\n| RabbitMQ Management | http://localhost:15672 | Message broker UI (guest/guest) |\n\n### Login Credentials\n\n**Admin:**\n\n| Role | Email | Password |\n|---|---|---|\n| Super Admin | `admin@gateway.local` | `changeme` |\n\n**Sample users** (seeded in dev/uat only — all share the password `password123`):\n\n| Email | Role | What to explore |\n|---|---|---|\n| `alice@acme-corp.com` | `API_PUBLISHER_ADMIN` | Publishing APIs, managing team subscriptions |\n| `carol@globex.io` | `PLATFORM_ADMIN` | Admin portal, analytics, user management |\n| `dave@globex.io` | `DEVELOPER` | Developer portal, Try-It console, subscriptions |\n\nAdditional seeded users for every role (`API_PUBLISHER`, `VIEWER`, `AUDITOR`, etc.) are defined in `db-changelog/` seed files. These accounts exist **only in dev and UAT profiles** and are never created in production.\n\n---\n\n## Configuration\n\nAll services are configured through environment variables. A pre-configured `.env` file is included for Docker — no changes needed for local development.\n\nCopy `.env.example` to `.env` for production deployments and fill in your values.\n\n| Variable | Docker Default | Local Default | Description |\n|---|---|---|---|\n| `GATEWAY_ENV` | `dev` | `dev` | Environment profile (`dev`, `staging`, `prod`) |\n| `DB_HOST` | `postgres` | `localhost` | PostgreSQL host |\n| `DB_PORT` | `5432` | `5432` | PostgreSQL port |\n| `DB_NAME` | `gateway` | `gateway` | PostgreSQL database name |\n| `DB_USERNAME` | `postgres` | `postgres` | PostgreSQL username |\n| `DB_PASSWORD` | `postgres` | `postgres` | PostgreSQL password |\n| `RABBITMQ_HOST` | `rabbitmq` | `localhost` | RabbitMQ host |\n| `RABBITMQ_PORT` | `5672` | `5672` | RabbitMQ AMQP port |\n| `RABBITMQ_USERNAME` | `guest` | `guest` | RabbitMQ username |\n| `RABBITMQ_PASSWORD` | `guest` | `guest` | RabbitMQ password |\n| `RABBITMQ_VHOST` | `/cem` | `/cem` | RabbitMQ virtual host |\n| `JWT_ISSUER_URI` | `http://identity-service:8081` | `http://localhost:8081` | JWT token issuer URI |\n| `IDENTITY_SERVICE_URL` | `http://identity-service:8081` | `http://localhost:8081` | Internal identity service URL |\n| `MAIL_HOST` | `localhost` | `localhost` | SMTP server host |\n| `MAIL_PORT` | `1025` | `1025` | SMTP server port |\n| `NEXT_PUBLIC_API_URL` | `http://localhost:8082` | `http://localhost:8082` | Management API URL (browser) |\n| `NEXT_PUBLIC_IDENTITY_URL` | `http://localhost:8081` | `http://localhost:8081` | Identity service URL (browser) |\n| `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:8080` | `http://localhost:8080` | Gateway runtime URL (browser) |\n| `NEXT_PUBLIC_ANALYTICS_URL` | `http://localhost:8083` | `http://localhost:8083` | Analytics service URL (browser) |\n\n\u003e **Note:** `NEXT_PUBLIC_*` variables are accessed from the browser, so they use `localhost` even in Docker. Internal service-to-service URLs use Docker container names. Database schemas are created automatically and managed with Liquibase migrations.\n\n---\n\n## Deployment Modes\n\n### Standard Mode (PostgreSQL only)\n\nThe default mode — suitable for most deployments. All data (including analytics) is stored in PostgreSQL.\n\n```bash\ncd deploy/docker\ndocker compose up -d\n```\n\n### High-Throughput Mode (PostgreSQL + ClickHouse)\n\nFor deployments with very high analytics ingestion volume (billions of request logs, long retention windows, or heavy ad-hoc reporting), enable [ClickHouse](https://clickhouse.com/) as the analytics backend while keeping everything else in PostgreSQL.\n\n#### Why ClickHouse?\n\n| Challenge | PostgreSQL | ClickHouse |\n|---|---|---|\n| **Write throughput** | ~5K-10K inserts/sec | 500K+ inserts/sec |\n| **Storage efficiency** | Row-based, large on disk | Columnar, 10-20x compression |\n| **Aggregation queries** | Slows down on 100M+ rows | Sub-second on billions of rows |\n| **Data retention** | Expensive DELETE operations | Built-in TTL auto-expiry |\n| **Resource contention** | Analytics writes compete with API management reads | Dedicated engine, no contention |\n\n#### What moves to ClickHouse\n\nOnly high-volume analytics data moves. Everything else stays in PostgreSQL:\n\n| Data | Store | Reason |\n|---|---|---|\n| `request_logs` (every API request) | **ClickHouse** | High-volume writes, time-series queries |\n| `metrics_1m`, `metrics_1h`, `metrics_1d` | **ClickHouse** | Aggregated rollups, large scans |\n| Real-time dashboards, SSE streaming | **ClickHouse** | Fast aggregation over recent data |\n| Custom report builder queries | **ClickHouse** | Ad-hoc analytics on large datasets |\n| APIs, routes, plans, subscriptions | PostgreSQL | Relational, low volume |\n| Users, roles, sessions, API keys | PostgreSQL | Transactional, relational |\n| Notification templates, delivery logs | PostgreSQL | Low volume, relational |\n\n#### Enabling ClickHouse\n\n1. Edit `deploy/docker/.env`:\n\n```properties\nSPRING_PROFILES_ACTIVE=dev,clickhouse\nCLICKHOUSE_HOST=clickhouse\nCLICKHOUSE_PORT=8123\nCLICKHOUSE_DB=gateway_analytics\n```\n\n2. Start with the ClickHouse profile:\n\n```bash\ndocker compose --profile clickhouse up -d\n```\n\n#### How the switch works\n\nThe analytics-service uses a strategy pattern with Spring profiles — the concrete implementation is selected at startup based on which profile is active:\n\n![RequestLogStore strategy pattern](architecture/request-log-store-strategy.svg)\n\nAll other services are completely unaffected — they always use PostgreSQL.\n\n#### Migrating existing data to ClickHouse\n\n```bash\n./scripts/migrate-to-clickhouse.sh\n```\n\n---\n\n## Performance\n\nWaterwall's `gateway-runtime` is a custom reverse proxy built on Spring Boot + Tomcat with Java 21 virtual threads and Apache HttpClient 5 connection pooling. Owning the hot path end-to-end enabled the optimizations below.\n\n### Benchmark setup\n\nLoad-tested with [Vegeta](https://github.com/tsenart/vegeta) running all 7 services, PostgreSQL, and RabbitMQ **on a single machine** (Windows 11, AMD Ryzen 9 7945HX, 32 GB RAM).\n\n### Full results\n\n| Rate | Success | p50 | p95 | p99 | Total Requests |\n|---:|:---:|---:|---:|---:|---:|\n| 100 rps | 100% | 1.2 ms | 3.3 ms | 12.5 ms | 1,500 |\n| 500 rps | 100% | 1.1 ms | 4.2 ms | 9.9 ms | 7,500 |\n| 1,000 rps | 100% | 1.5 ms | 8.0 ms | 20.8 ms | 15,000 |\n| 2,000 rps | 100% | 1.3 ms | 8.0 ms | 20.1 ms | 119,998 |\n| 3,000 rps | 100% | 3.5 ms | 22.0 ms | 34.6 ms | 45,000 |\n| 4,000 rps | 100% | 8.5 ms | 30.5 ms | 65.3 ms | 60,000 |\n\n100% success rate from 100 up to 4,000 rps, with sub-millisecond-to-single-digit-millisecond medians across the range — on a single laptop running **every component** of the stack.\n\n### Key optimizations\n\n- **Virtual-thread pinning fix** — moved RabbitMQ publishing to dedicated platform thread pools, eliminating carrier-thread starvation on synchronized AMQP blocks\n- **Lock-free route configuration** — volatile references to immutable collections, no read contention on the hot path\n- **Async access logging** — fully decoupled from the request lifecycle\n- **Backpressure filter** — returns `503 Retry-After` under overload instead of dropping connections\n- **Early route rejection** — unmatched routes fail at filter order 5, before any heavy work\n\nBenchmarks were run on Windows. Contributions of Linux benchmark data are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## Documentation\n\n### User Guide\n\nFor comprehensive setup instructions, configuration guides, and usage documentation, see the **[Waterwall User Guide](https://waterwall.dev/docs/index.html)**.\n\n### API Documentation\n\nEach backend service exposes health and info endpoints via Spring Boot Actuator:\n\n```\nGET /actuator/health/liveness\nGET /actuator/health/readiness\n```\n\nFull OpenAPI documentation is available at each service's `/v3/api-docs` endpoint when running in development mode.\n\n---\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to submit issues, feature requests, and pull requests.\n\n---\n\n## License\n\nThis project is licensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDevLink-Tech-Academy%2Fwaterwall-api-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDevLink-Tech-Academy%2Fwaterwall-api-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDevLink-Tech-Academy%2Fwaterwall-api-gateway/lists"}