The architecture behind DevNotify, written from the repository README. Source files were not independently inspected, so treat file paths as pointers to check.
The asynchronous path from an external system to a delivered notification, as described in the README. Ingestion does not wait on email delivery, so the sender gets its 202 Accepted early.
An external system sends POST /webhooks/{tenantSlug}/ingest. A tenant filter resolves the team from the slug before the request reaches the controller.
Spring MVC filter chain (TenantFilter, JwtAuthFilter, SecurityConfig)
The sender signs the payload with HMAC-SHA256 using the tenant's API key and puts the hex digest in X-Webhook-Signature. The platform recomputes it and compares in constant time. The secret itself never crosses the network.
HmacUtil with MessageDigest.isEqual
The raw payload is stored as JSONB in webhook_events with status RECEIVED. This runs in its own bean so the transaction commits before anything is published.
PostgreSQL 16, Flyway (WebhookPersistenceService)
The event is published to RabbitMQ on devnotify.events. Messages that fail processing go to a dead letter queue, where they stay available for inspection instead of being retried forever.
RabbitMQ 3.13 (NotificationProducer, dead letter queue)
A consumer hands the event to NotificationProcessingService. Rules match on optional event type and source, where an empty field means catch-all. Matching rules produce notification records. Active rules are cached in Redis and evicted whenever a rule changes.
NotificationConsumer (thin adapter)
Redis 7, CachedRule DTO
Each notification fans out to its rule's channels. Email is sent asynchronously so SMTP latency never blocks the queue. WebSocket push goes to the individual member and to a tenant-wide topic. Notifications are also indexed for full-text search, and every delivery attempt is recorded as PENDING, SENT or FAILED.
EmailService (Mailtrap sandbox in the documented setup)
Spring STOMP and SockJS
Elasticsearch 8.15
A gRPC server on port 9090 exposes NotificationProcessor.ProcessWebhookEvent. It calls the same NotificationProcessingService as the queue consumer, so there is one definition of what processing an event means.
It exists for cases that need an immediate result, such as testing a rule now. Today everything runs in one process, so the contract and client/server pair work, but independent scaling of a split service does not exist yet.
Seven behaviours from the README, each with the reasoning the repository gives for it.
WebhookPersistenceService is a separate bean from the code that publishes to RabbitMQ. The database transaction commits before the message goes out.
Spring applies @Transactional through a bean's proxy, so a call within the same class bypasses it. Splitting the bean means a queued message cannot point at a row that was never committed.
Webhooks are authenticated with HMAC-SHA256 over the payload, keyed by the tenant's API key, and checked with a constant-time comparison.
The shared secret is never sent, and the comparison takes the same time wherever the signatures differ.
A rule names an optional event type, an optional source, and a list of channels, EMAIL or WEBSOCKET. Leaving type and source empty creates a catch-all.
A team changes what it hears about through the REST API instead of redeploying.
Every notification has one delivery row per channel, with status, attempt time, delivery time and a failure reason.
When an email does not arrive, the record shows whether it was attempted and why it failed.
Tenants use cache-aside. Notification rules use invalidate-on-write. Rules are cached as a flat CachedRule DTO rather than as JPA entities.
A stale tenant corrects itself after one slow read. A stale rule would silently misroute notifications for minutes. Caching entities directly hit a real serialization bug with lazy-loaded proxies, which the DTO avoids.
GET /api/v1/tenants/{slug}/notifications/search?q= runs a full-text query against Elasticsearch.
Past notifications can be found by their content, from the same API that creates them.
gRPC and Protocol Buffers define a ProcessWebhookEvent call that reuses the queue consumer's business logic.
Ingestion stays asynchronous so senders never wait on email. gRPC serves callers that want the result immediately.
Paths follow the project structure listed in the README.
The schema is version-controlled SQL. Hibernate validates it at startup and never generates it.
Webhook bodies are stored as received and interpreted downstream according to their source.
JWT validation is signature-only, with no database round trip. Browsers cannot set headers on WebSocket connections, so the token travels as a query parameter and is checked in the handshake interceptor.
POST /webhooks/{tenantSlug}/ingest (HMAC signature, plus X-Event-Type and X-Event-Source headers). GET /webhooks/{tenantSlug}/eventsPOST /api/v1/auth/register, POST /api/v1/auth/login (returns a JWT)POST and GET /api/v1/tenants, GET /api/v1/tenants/{slug} (cached), PATCH /api/v1/tenants/{id}/suspend (evicts cache)POST and GET /api/v1/tenants/{slug}/rules, DELETE .../rules/{ruleId} deactivatesGET /api/v1/tenants/{slug}/notifications/search?q=ws://localhost:8080/ws?token=<jwt>, subscribe to /user/queue/notifications or /topic/tenant/{tenantSlug}NotificationProcessor.ProcessWebhookEvent on port 9090. Manual test: POST /api/v1/grpc-test/process/{webhookEventId}Requires Java 21+, Docker and Postman. Start the four services, fill in the gitignored application.yml (JWT secret, Mailtrap credentials, Redis, Elasticsearch and gRPC settings), then build and run.
docker run --name devnotify-postgres -e POSTGRES_DB=devnotify -e POSTGRES_USER=devnotify -e POSTGRES_PASSWORD=devnotify -p 5432:5432 -d postgres:16
docker run --name devnotify-rabbitmq -e RABBITMQ_DEFAULT_USER=guest -e RABBITMQ_DEFAULT_PASS=guest -p 5672:5672 -p 15672:15672 -d rabbitmq:3-management
docker run --name devnotify-redis -p 6379:6379 -d redis:7-alpine
docker run --name devnotify-elasticsearch -e discovery.type=single-node -e xpack.security.enabled=false -p 9200:9200 -d docker.elastic.co/elasticsearch/elasticsearch:8.15.0
./gradlew clean build -x test
./gradlew bootRunThe README then walks through a ten step end-to-end test: create a tenant, register a member, create a rule, connect a WebSocket, sign and send a webhook, and check the browser, Mailtrap inbox, search and gRPC re-processing. A local Redis on port 6379 can shadow the container, so check docker ps.
The README marks all five build phases complete. It also lists gaps, and a few more follow from its API reference. There is no hosted service, no published benchmark and no commercial offering.