Implement notifications service with shared messaging and email drivers (#36)

backend/notifications/interface/README.md

@@ -0,0 +1,41 @@
+# Notifications service contract
+
+This independent module owns the public internal-service contract. The canonical
+source is `proto/v1/interface.proto`; it defines `Send`, `Get`, requests, statuses
+and email/SMS/push/Telegram targets. The executable currently implements email.
+
+From the repository root, `make generate-notifications` produces Go/gRPC client
+bindings in `notifications/v1`. Generated `.pb.go` files are ignored and must not
+be committed. Both backend validation targets generate bindings before compiling.
+The generators are pinned in the Makefile; install `protoc` separately.
+
+`make package-notifications-interface` creates a distributable source archive and
+a standalone Go client-module archive under `dist/`. Client consumers can generate
+bindings for their own language from the source archive. The Go archive contains
+the generated bindings and its own go.mod/go.sum, with no executable or shared
+infrastructure dependency. Archive generation does not upload to a registry.
+
+Internal Go consumers use the module
+`git.sendico.io/tech/sxchnge/notifications/interface` and import
+`git.sendico.io/tech/sxchnge/notifications/interface/notifications/v1`. Within this
+checkout, use a local replace to this directory and generate before building.
+
+Calls require TLS and `authorization: Bearer <service-token>` metadata. The service
+maps tokens to configured caller identities. Callers authorize user/destination
+ownership and preferences before sending; this contract is not a public user API.
+
+Parameters are string values keyed by template parameter name. The entire request
+is validated before persistence. An identical idempotency key/request returns the
+original resource, even after completion or expiry. A changed request conflicts.
+Keys are scoped to the authenticated caller and retained at least seven days;
+Mongo TTL deletion is asynchronous. Expiry defaults to 24 hours and cannot exceed
+24 hours. One email target is accepted; other declared channels return UNIMPLEMENTED.
+
+ACCEPTED means provider acceptance, not delivery or reading. UNKNOWN means the
+provider may have sent the message and automatic replay is unsafe. DELIVERED is
+reserved for a future receipt implementation. Get never exposes recipient addresses,
+rendered content, parameters, provider credentials or raw provider responses.
+
+Keep published template revisions and field numbers stable. Reserve removed
+protobuf field/enum names and numbers. Compatible additions belong in v1;
+incompatible changes require a new version.