m

Adjust endpoint

.gitea/workflows/check.yml

@@ -1,9 +0,0 @@
-name: check
-on: [push]
-jobs:
-    check:
-        runs-on: ubuntu-latest
-        steps:
-            # actions/checkout v4.2.2, 2026-02-22
-            - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-            - run: docker build .

.gitignore

@@ -21,7 +21,9 @@ node_modules/
 *.key
 
 # Go build artifacts
-backend-go/bin/
+backend/bin/
+backend/api
+backend/poller
 *.exe
 *.exe~
 *.dll
@@ -42,3 +44,4 @@ Prompts/
 
 # Logs
 *.log
+.claude

.prettierignore

@@ -1,7 +1,7 @@
 node_modules/
 frontend/dist/
 frontend/build/
-backend-go/bin/
+backend/bin/
 *.lock
 Prompts/
 .claude/

LICENSE

@@ -2,8 +2,7 @@ MIT License
 
 Copyright (c) 2026 Steven Jannette
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is

LLM_DEV_PROMPTS/.dockerignore

@@ -0,0 +1,3 @@
+.git
+node_modules
+.DS_Store

LLM_DEV_PROMPTS/.gitignore

@@ -0,0 +1,26 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+*.swp
+*.swo
+*~
+*.bak
+.idea/
+.vscode/
+*.sublime-*
+
+# Node
+node_modules/
+
+# Environment / secrets
+.env
+.env.*
+*.pem
+*.key
+
+# Prompts
+prompts/
+*prompts
+prompts*

LLM_DEV_PROMPTS/ANGULAR PROJECTS/CODE_STYLEGUIDE_ANGULAR.md

@@ -0,0 +1,47 @@
+You are an expert in TypeScript, Angular, and scalable web application development. You write functional, maintainable, performant, and accessible code following Angular and TypeScript best practices.
+
+## TypeScript Best Practices
+1. Use strict type checking
+2. Prefer type inference when the type is obvious
+3. Avoid the `any` type; use `unknown` when type is uncertain
+
+## Angular Best Practices
+1. Always use standalone components over NgModules
+2. Must NOT set `standalone: true` inside Angular decorators. It's the default in Angular v20+.
+3. Use signals for state management
+4. Implement lazy loading for feature routes
+5. Do NOT use the `@HostBinding` and `@HostListener` decorators. Put host bindings inside the `host` object of the `@Component` or `@Directive` decorator instead
+6. Use `NgOptimizedImage` for all static images.
+7. Note: `NgOptimizedImage` does not work for inline base64 images.
+
+## Accessibility Requirements
+1. It MUST pass all AXE checks.
+2. It MUST follow all WCAG AA minimums, including focus management, color contrast, and ARIA attributes.
+
+### Components
+1. Keep components small and focused on a single responsibility
+2. Use `input()` and `output()` functions instead of decorators
+3. Use `computed()` for derived state
+4. Set `changeDetection: ChangeDetectionStrategy.OnPush` in `@Component` decorator
+5. Prefer inline templates for small components
+6. Prefer Reactive forms instead of Template-driven ones
+7. Do NOT use `ngClass`, use `class` bindings instead
+8. Do NOT use `ngStyle`, use `style` bindings instead
+9. When using external templates/styles, use paths relative to the component TS file.
+
+## State Management
+1. Use signals for local component state
+2. Use `computed()` for derived state
+3. Keep state transformations pure and predictable
+4. Do NOT use `mutate` on signals, use `update` or `set` instead
+
+## Templates
+1. Keep templates simple and avoid complex logic
+2. Use native control flow (`@if`, `@for`, `@switch`) instead of `*ngIf`, `*ngFor`, `*ngSwitch`
+3. Use the async pipe to handle observables
+4. Do not assume globals like (`new Date()`) are available.
+
+## Services
+1. Design services around a single responsibility
+2. Use the `providedIn: 'root'` option for singleton services
+3. Use the `inject()` function instead of constructor injection

LLM_DEV_PROMPTS/A_EXISTING_REPO_CHECKLIST.md

@@ -0,0 +1,79 @@
+---
+title: Existing Repo Checklist
+last_modified: 2026-02-22
+---
+
+Use this checklist when starting work in a repo that may not conform to our repo policies.
+
+Plan first.  Structure work into discreet tasks, according to well-defined acceptance critera. Work on a feature branch for each work item. 
+
+**Always check your work** and fix gaps between it and the policies and acceptance creiteria before proceeding with the next task.
+
+# Formatting (do this first)
+
+- [ ] If the repo has never been formatted to our standards, run `make fmt` and
+      commit the result as a standalone branch/PR before any other
+      changes. Formatting diffs can be large and should not be mixed with
+      functional changes.
+
+# Required Files
+
+- [ ] `README.md` exists with all required sections (Description, Getting
+      Started, Rationale, Design, TODO, License, Author)
+- [ ] `LICENSE` file exists and matches the README
+- [ ] `REPO_POLICIES.md` exists and version date is current — fetch from
+      `https://github.com/kjannette/LLM_DEV_PROMPTS/blob/master/REPO_POLICIES.md`
+- [ ] `.gitignore` is comprehensive (OS, editor, language artifacts, secrets) —
+      fetch from `https://github.com/kjannette/LLM_DEV_PROMPTS/blob/master/.gitignore`
+      if missing
+- [ ] `Dockerfile` and `.dockerignore` exist; Dockerfile runs `make check` as a
+      build step — fetch `.dockerignore` from
+      `https://github.com/kjannette/LLM_DEV_PROMPTS/blob/master/.dockerignore`
+- [ ] Language-specific config:
+    - [ ] Go: `go.mod`, `go.sum`, `.golangci.yml` (fetch from
+          `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/.golangci.yml`)
+    - [ ] JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
+          (fetch from
+          `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/.prettierrc` and
+          `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/.prettierignore`)
+    - [ ] Python: `pyproject.toml`
+    - [ ] Docs/writing: `.prettierrc`, `.prettierignore` (same URLs as above)
+
+# Makefile
+
+- [ ] `Makefile` exists in root — reference
+      `https://github.com/kjannette/LLM_DEV_PROMPTS/blob/master/Makefile`
+- [ ] Has targets: `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`,
+      `hooks`
+- [ ] `make check` does not modify any files in the repo
+- [ ] `make test` has a 30-second timeout
+- [ ] `make test` runs real tests, not a no-op (at minimum, import/compile
+      check)
+- [ ] `make check` passes on current branch
+
+# Formatting
+
+- [ ] Platform-standard formatter is configured (`black`, `prettier`, `go fmt`)
+- [ ] Default formatter config, only exception: four-space indents (except Go)
+- [ ] All files pass `make fmt-check`
+
+# Git Hygiene
+
+- [ ] Pre-commit hook is installed (`make hooks`)
+- [ ] No secrets in the repo (`.env`, keys, credentials)
+- [ ] No mutable references in Dockerfiles or scripts (tags, `@latest`) — all
+      pinned by cryptographic hash with version/date comment
+- [ ] Using `yarn`, not `npm` (JS projects)
+
+# Directory Structure
+
+- [ ] No unnecessary files in repo root
+- [ ] Files organized into canonical subdirectories (`bin/`, `cmd/`, `docs/`,
+      `internal/`, `static/`, etc.)
+- [ ] Go migrations in `internal/db/migrations/` and embedded in binary
+
+# Final
+
+- [ ] `make check` passes
+- [ ] `docker build` succeeds
+- [ ] Commit and merge fixes before starting your actual task

LLM_DEV_PROMPTS/B_NEW_REPO_CHECKLIST.md

@@ -0,0 +1,88 @@
+---
+title: New Repo Checklist
+last_modified: 2026-02-22
+---
+
+Use this checklist when creating a new repository from scratch. Follow the steps
+in order. Full policies are at
+`https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/prompts/REPO_POLICIES.md`.
+
+Template files can be fetched from:
+`https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/<path>`
+
+# 1. Initialize
+
+- [ ] `git init`
+- [ ] Ask the user for the license (MIT, GPL, or WTFPL)
+
+# 2. First Commit (README only)
+
+- [ ] Create `README.md` with all required sections:
+    - [ ] **Description**: name, purpose, category, license, author
+    - [ ] **Getting Started**: copy-pasteable code block
+    - [ ] **Rationale**: why does this exist?
+    - [ ] **Design**: how is it structured?
+    - [ ] **TODO**: initial task list
+    - [ ] **License**: matches chosen license
+    - [ ] **Author**: [@sjdev](https://sjdev.co)
+- [ ] `git add README.md && git commit`
+
+# 3. Scaffolding (feature branch)
+
+- [ ] `git checkout -b initial-scaffolding`
+
+## Fetch Template Files
+
+- [ ] `.gitignore` — fetch from
+      `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/.gitignore`, extend for
+      language-specific artifacts
+- [ ] `.editorconfig` — fetch from
+      `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/.editorconfig`
+- [ ] `Makefile` — fetch from
+      `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/Makefile`, adapt
+      targets for the project's language and tools
+- [ ] For JS/docs repos: `.prettierrc` and `.prettierignore` — fetch from
+      `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/.prettierrc` and
+      `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/.prettierignore`
+
+## Create Project Files
+
+- [ ] `LICENSE` file matching the chosen license
+- [ ] `REPO_POLICIES.md` — fetch from
+      `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/prompts/REPO_POLICIES.md`
+- [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from
+      `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/.dockerignore`
+    - All Dockerfiles must run `make check` as a build step
+    - Server: also builds and runs the application
+    - Non-server: brings up dev environment and runs `make check`
+    - Image pinned by sha256 hash with version/date comment
+- [ ] Language-specific:
+    - [ ] Go: `go mod init sjdev.co/go/<name>`, `.golangci.yml`
+    - [ ] JS: `npm init`, `npm i --dev prettier`
+    - [ ] Python: `pyproject.toml`
+
+## Configure Makefile
+
+- [ ] `make test` — runs real tests, not a no-op (30-second timeout)
+- [ ] `make lint` — runs linter
+- [ ] `make fmt` — formats code (writes)
+- [ ] `make fmt-check` — checks formatting (read-only)
+- [ ] `make check` — prereqs: `test`, `lint`, `fmt-check`; must not modify files
+- [ ] `make docker` — builds Docker image
+- [ ] `make hooks` — installs pre-commit hook
+
+# 4. Verify
+
+- [ ] `make check` passes
+- [ ] `make docker` succeeds
+- [ ] No exposed secrets in repo
+- [ ] No mutable image/package references
+- [ ] No unnecessary files in repo root
+- [ ] All dates written as YYYY-MM-DD
+
+# 5. Merge and Set Up
+
+- [ ] Commit, merge to `main`
+- [ ] `make hooks` to install pre-commit hook
+- [ ] Add remote and push
+- [ ] Verify `main` passes `make check`

LLM_DEV_PROMPTS/C_GENERAL_CODE_STYLEGUIDE.md

@@ -0,0 +1,76 @@
+---
+title: Code Styleguide
+last_modified: 2026-02-22
+---
+
+# All
+
+1. Every repo must have a `Makefile` and a `Dockerfile`. See
+   [Repository Policies](https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/prompts/REPO_POLICIES.md)
+   for required targets and conventions.
+
+2. Credentials and/or secrets should never be committed to any repository, even private ones. Store secrets in environment variables, and if they are absolutely required, check on startup to make sure they are set/non-default and complain loudly if not. Exception, sometimes: public keys. (Public keys can still sometimes be secrets for operational security reasons.)
+
+3. KISS & DRY: Keep it simple, stupid (KISS) and Don't Repeat Yourself (DRY) to minimize complexity and technical debt.
+
+4. Composition over Inheritance: Prefer combining simple objects to build complex ones rather than creating deep class hierarchies.
+
+5. Avoid nesting `if` statements. If you have more than one level of nesting,
+   consider inverting the condition and using `return` to exit early.
+
+6. Almost all services/servers should accept their configuration via environment
+   variables. Only go full config file if absolutely necessary.
+
+7. For services/servers, log JSON to stdout. This makes it easier to parse and
+   aggregate logs when run under `docker`. Use structured logging whenever
+   possible. You may detect if the output is a terminal and pretty-print the
+   logs in that case.
+
+8. Debug mode is enabled by setting the environment variable `DEBUG` to a
+   non-empty string. This should enable verbose logging and such. It will never
+   be enabled in prod.
+
+9. For services/servers, make a healthcheck available at
+   `/.well-known/healthcheck`. The response must have a
+   `Content-Type: application/json` header and return a JSON object containing
+   the service's name, uptime, and a key of `"status"` with a value of `"ok"`.
+   Return a 200 for healthy, 5xx for unhealthy.
+
+10. If possible, for services/servers, include a /metrics endpoint that returns
+    Prometheus-formatted metrics. This is not required for all services, but is a
+    nice-to-have.
+
+# Bash / Shell
+
+1. Use `[[` instead of `[` for conditionals. 
+
+2. Use `$( )` instead of backticks.
+
+3. Use `#!/usr/bin/env bash` as the shebang line. This allows the script to be
+   run on systems where `bash` is not in `/bin`.
+
+4. Use `set -euo pipefail` at the top of every script. This will cause the
+   script to exit if any command fails, or if a variable is used before it is set.
+
+5. Use `pv` for progress bars when piping data through a command.
+
+6. Put all code in functions, even a main function. Define all functions then
+   call main at the bottom of the file.
+
+# Docker Containers (for services)
+
+1. Use `runit` with `runsvinit` as the entrypoint for all containers. This
+   allows for easy service management and logging. In startup scripts
+   (`/etc/service/*/run`) in the container, put a `sleep 1` at the top of the
+   script to avoid spiking the cpu in the case of a fast-exiting process (such
+   as in an error condition). This also limits the maximum number of error
+   messages in logs to 86400/day.
+
+# Author
+
+[@sjdev](https://sjdev.co)
+<[sj@sjdev.co(mailto:sj@sjdev.berlin)>
+
+# License
+
+MIT. See [LICENSE](../LICENSE).

LLM_DEV_PROMPTS/D_REPO_POLICIES.md

@@ -6,12 +6,12 @@ last_modified: 2026-02-22
 This document covers repository structure, tooling, and workflow standards. Code
 style conventions are in separate documents:
 
-- [Code Styleguide](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE.md)
+- [Code Styleguide](https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/prompts/CODE_STYLEGUIDE.md)
   (general, bash, Docker)
-- [Go](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_GO.md)
-- [JavaScript](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_JS.md)
-- [Python](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_PYTHON.md)
-- [Go HTTP Server Conventions](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/GO_HTTP_SERVER_CONVENTIONS.md)
+- [Go](https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/prompts/CODE_STYLEGUIDE_GO.md)
+- [JavaScript](https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/prompts/CODE_STYLEGUIDE_JS.md)
+- [Python](https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/prompts/CODE_STYLEGUIDE_PYTHON.md)
+- [Go HTTP Server Conventions](https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/prompts/GO_HTTP_SERVER_CONVENTIONS.md)
 
 ---
 
@@ -37,7 +37,7 @@ style conventions are in separate documents:
   `make test`, `make lint`, `make fmt` (writes), `make fmt-check` (read-only),
   `make check` (prereqs: `test`, `lint`, `fmt-check`), `make docker`, and
   `make hooks` (installs pre-commit hook). A model Makefile is at
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
+  `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/Makefile`.
 
 - Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
   instead of invoking the underlying tools directly. The Makefile is the single
@@ -59,10 +59,6 @@ style conventions are in separate documents:
   `make check`. For server repos, `make check` should run as an early build
   stage before the final image is assembled.
 
-- Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `docker build .` on push. Since the Dockerfile already runs `make check`,
-  a successful build implies all checks pass.
-
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
   two exceptions: four-space indents (except Go), and `proseWrap: always` for
@@ -95,7 +91,7 @@ style conventions are in separate documents:
 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
   editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
   Fetch the standard `.gitignore` from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/.gitignore` when setting up
   a new repo.
 
 - Never use `git add -A` or `git add .`. Always stage files explicitly by name.
@@ -107,7 +103,7 @@ style conventions are in separate documents:
 
 - `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
   manually by the user. Fetch from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
+  `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/.golangci.yml`.
 
 - When pinning images or packages by hash, add a comment above the reference
   with the version and date (YYYY-MM-DD).
@@ -124,7 +120,7 @@ style conventions are in separate documents:
 - `README.md` is the primary documentation. Required sections:
     - **Description**: First line must include the project name, purpose,
       category (web server, SPA, CLI tool, etc.), license, and author. Example:
-      "µPaaS is an MIT-licensed Go web application by @sneak that receives
+      "µPaaS is an MIT-licensed Go web application by @sjdev that receives
       git-frontend webhooks and deploys applications via Docker in realtime."
     - **Getting Started**: Copy-pasteable install/usage code block.
     - **Rationale**: Why does this exist?
@@ -134,11 +130,11 @@ style conventions are in separate documents:
       left off.
     - **License**: MIT, GPL, or WTFPL. Ask the user for new projects. Include a
       `LICENSE` file in the repo root and a License section in the README.
-    - **Author**: [@sneak](https://sneak.berlin).
+    - **Author**: [@sjdev](https://sjdev.co).
 
 - First commit of a new repo should contain only `README.md`.
 
-- Go module root: `sneak.berlin/go/<name>`. Always run `go mod tidy` before
+- Go module root: `sjdev.co/go/<name>`. Always run `go mod tidy` before
   committing.
 
 - Use SemVer.
@@ -175,14 +171,13 @@ style conventions are in separate documents:
 
 - When setting up a new repo, files from the `prompts` repo may be used as
   templates. Fetch them from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/<path>`.
+  `https://github.com/kjannette/LLM_DEV_PROMPTS/raw/branch/main/<path>`.
 
-- New repos must contain at minimum:
-    - `README.md`, `.git`, `.gitignore`, `.editorconfig`
+- New repos must contain:
+    - `README.md`, `.git`, `.gitignore`
     - `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
     - `Makefile`
     - `Dockerfile`, `.dockerignore`
-    - `.gitea/workflows/check.yml`
     - Go: `go.mod`, `go.sum`, `.golangci.yml`
-    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
+    - JS: `package.json`, `.prettierrc`, `.prettierignore`
     - Python: `pyproject.toml`

LLM_DEV_PROMPTS/Dockerfile

@@ -0,0 +1,11 @@
+# node 22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
+
+RUN apk add --no-cache make
+
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+
+RUN make check

LLM_DEV_PROMPTS/GOLANG PROJECTS/CODE_STYLEGUIDE_GO.md

@@ -0,0 +1,575 @@
+---
+title: Code Styleguide — Go
+last_modified: 2026-02-22
+---
+
+1.  Hard wrap long lines at 80 characters or less.
+
+2.  Always `go fmt` code before committing it. The one, rare exception is
+    when committing code that is not yet syntactically valid.  This should
+    only happen pre-v0.0.1 or on a non-`main` branch.
+
+3.  Even if you planning to deal with only positive integers, use
+    `int`/`int64` types instead of `uint`/`uint64` types. This is for
+    consistency and compatibility with the standard library.
+
+4.  Any project with more than 3 modules should use the `go.uber.org/fx` 
+    injection framework.
+
+5.  Embed the git commit hash into the binary and include it in startup logs and
+    in health check output, to aid correlattion of running instances with their
+    code. Do not include build time or build user, which will make the build 
+    nondeterministic.
+
+    Example relevant Makefile sections:
+
+    Given a `main.go` like:
+
+    ```go
+    package main
+
+    import (
+        "fmt"
+    )
+
+    var (
+        Version   string
+        Buildarch string
+    )
+
+    func main() {
+        fmt.Printf("Version: %s\n", Version)
+        fmt.Printf("Buildarch: %s\n", Buildarch)
+    }
+    ```
+
+    ```make
+    VERSION := $(shell git describe --always --dirty)
+    BUILDARCH := $(shell uname -m)
+
+    GOLDFLAGS += -X main.Version=$(VERSION)
+    GOLDFLAGS += -X main.Buildarch=$(BUILDARCH)
+
+    # osx can't statically link apparently?!
+    ifeq ($(UNAME_S),Darwin)
+            GOFLAGS := -ldflags "$(GOLDFLAGS)"
+    endif
+
+    ifneq ($(UNAME_S),Darwin)
+            GOFLAGS = -ldflags "-linkmode external -extldflags -static $(GOLDFLAGS)"
+    endif
+
+    ./httpd: ./pkg/*/*.go ./internal/*/*.go cmd/httpd/*.go
+        go build -o $@ $(GOFLAGS) ./cmd/httpd/*.go
+    ```
+6.  Use `log/slog` for structured logging. Import `sjdev.co/go/simplelog`
+    for sensible defaults. Example:
+
+    ```go
+    package main
+
+    import (
+        "log/slog"
+        _ "sjdev.co/go/simplelog"
+    )
+
+    func main() {
+        slog.Info("Starting up")
+    }
+    ```
+
+7.  Commit at least a single test file to check compilation. The test file can
+    be empty, but should exist. This ensuress that `go test ./...` will
+    always function as a syntax check.
+
+8.  When fixing a specific bug, write a test that reproduces it, before 
+    fixing it. This will fix the experience of discovering the bug and the fix into 
+    the repo history.
+
+9.  For anything beyond a simple script or tool, or anything that is going to
+    run in any sort of "production" anywhere, make sure it passes
+    `golangci-lint`.
+
+10. Write a `Dockerfile` for every repo, even if it only runs the tests and
+    linting. `docker build .` should always make sure that the code is in an
+    able-to-be-compiled state, linted, and any tests run. The Docker build
+    should fail if linting doesn't pass.
+
+11. Every repo must have a `Makefile`. See
+    [Repository Policies](https://github.com/kjannette/LLM_DEV_PROMPTS/blob/master/REPO_POLICIES.md)
+    for required targets and conventions.
+
+12. If you are writing a single-module library, `.go` files are permissible in the repo
+    root.
+
+13. If you are writing a multi-module project, put all `.go` files in a `pkg/`
+    or `internal/` subdirectory. `internal/` is for modules used only by the
+    current repo, and `pkg/` is for modules that can be consumed externally.
+
+14. Binaries go in `cmd/` directories. Each binary should have its own
+    directory. This is to keep the root clean and to make it easier to distinguish a 
+    library from a binary. Only package `main` files should be in
+    `cmd/*` directories.
+
+15. Keep the `main()` function as small as possible.
+
+16. Keep the `main` package as small as possible. Move as much code as is
+    feasible to a library package, even if it's an internal one. `main` is
+    an entrypoint to the code, not a place for implementations. Exception:
+    single-file scripts.
+
+17. HTTP HandleFuncs should be returned from methods or functions that need to
+    handle HTTP requests. Don't use methods or your top level functions as
+    handlers.
+
+18. Provide a .gitignore file that ignores at least `*.log`, `*.out`, and
+    `*.test` files, as well as any binaries.
+
+19. Constructors should be called `New()` whenever possible. `modulename.New()`
+    works great if you name the packages properly.
+
+20. Don't make packages too big. Break them up.
+
+21. Don't make functions or methods too big. Break them up.
+
+22. Use descriptive names for functions and methods. Don't be afraid to make
+    them a bit long.
+
+23. Use descriptive names for modules and filenames. Avoid generic names like
+    `server`. `util` is banned.
+
+24. Constructors should take a Params struct if they need more than 1-2
+    arguments. Positional arguments are an endless source of bugs and should be
+    avoided whenever possible.
+
+25. Use `context.Context` for all functions that need it. If you don't need it,
+    you can pass `context.Background()`. Anything long-running should get and
+    abide by a Context. A context does not count against your number of function
+    or method arguments for purposes of calculating whether or not you need a
+    Params struct, because the `ctx` is always first.
+
+26. Contexts are always named `ctx`.
+
+27. Use `context.WithTimeout` or `context.WithDeadline` for any function that
+    could potentially run for a long time. This is especially true for any
+    function that makes a network call. Sane timeouts are essential.
+
+28. If a structure/type is only used in one function or method, define it there.
+    If it's used in more than one, define it in the package. Keep it close to
+    its usages. For example:
+
+    ```go
+    func (m *Mothership) tvPost() http.HandlerFunc {
+
+        type MSTVRequest struct {
+                URL string `json:"URL"`
+        }
+
+        type MSTVResponse struct {
+        }
+
+        return func(w http.ResponseWriter, r *http.Request) {
+            // parse json from request
+            var reqParsed MSTVRequest
+            err = json.NewDecoder(r.Body).Decode(&reqParsed)
+            ...
+
+            if err != nil {
+                    SendErrorResponse(w, MSGenericError)
+                    return
+            }
+
+            log.Info().Msgf("Casting to %s: %s", tvName, streamURL)
+            SendSuccessResponse(w, &MSTVResponse{})
+        }
+    }
+    ```
+
+29. Avoid global state, especially global variables. If you need to store state
+    that is global to your launch or application instance, use a package
+    `globals` or `appstate` with a struct and a constructor and require it as a
+    dependency in your constructors. This will allow consumers to be more easily
+    testable and will make it easier to reason about the state of your
+    application. Alternately, if your dependency graph allows for it, put it in
+    the main struct/object of your application, but remember that this harms
+    testability.
+
+30. Package-global "variables" are ok if they are constants, such as static
+    strings or integers or errors.
+
+31. Whenever possible, avoid hardcoding numbers or values in your code. Use
+    descriptively-named constants instead. Recall the famous SICP quote:
+    "Programs must be written for people to read, and only incidentally for
+    machines to execute." Rather than comments, a descriptive constant name is
+    much cleaner.
+
+    Example:
+
+    ```go
+
+    const jsonContentType = "application/json; charset=utf-8"
+
+    func (s *Handlers) respondJSON(w http.ResponseWriter, r *http.Request, data interface{}, status int) {
+         w.WriteHeader(status)
+         w.Header().Set("Content-Type", jsonContentType)
+         ...
+     }
+    ```
+
+32. Define your struct types near their constructors.
+
+33. Do not create packages whose sole purpose is to hold type definitions.
+    Packages named `types`, `domain`, or `models` that contain only structs and
+    interfaces (with no behavior) are a code smell. Define types alongside the
+    code that uses them. Type-only packages force consuming packages into alias
+    imports and circular-dependency gymnastics, and indicate that the package
+    boundaries were drawn around nouns instead of responsibilities. If multiple
+    packages need the same type, put it in the package that owns the behavior,
+    or in a small, focused interface package — not in a grab-bag types package.
+
+34. When defining custom string-based types (e.g. `type ImageID string`),
+    implement `fmt.Stringer`. Use `.String()` at SDK and library boundaries
+    instead of `string(v)`. This makes type conversions explicit, grep-able, and
+    consistent across the codebase. Example:
+
+    ```go
+    type ContainerID string
+
+    func (id ContainerID) String() string { return string(id) }
+
+    // At the Docker SDK boundary:
+    resp, err := c.docker.ContainerStart(ctx, id.String(), opts)
+    ```
+
+35. Define your interface types near the functions that use them, or if you have
+    multiple conformant types, put the interface(s) in their own file.
+
+36. Define errors as package-level variables. Use a descriptive name for the
+    error. Use `errors.New` to create the error. If you need to include
+    additional information in the error, use a struct that implements the
+    `error` interface.
+
+37. Use lowerCamelCase for local function/variable names. Use UpperCamelCase for
+    type names, and exported function/variable names. Use snake_case for JSON
+    keys. Use lowercase for filenames.
+
+38. Explicitly specify UTC for datetimes unless you have a very good reason not
+    to. Use `time.Now().UTC()` to get the current time in UTC.
+
+39. String dates should always be ISO8601 formatted. Use `time.Time.Format` with
+    `time.RFC3339` to get the correct format.
+
+40. Use `time.Time` for all date and time values. Do not use `int64` or `string`
+    for dates or times internally.
+
+41. When using `time.Time` in a struct, use a pointer to `time.Time` so that you
+    can differentiate between a zero value and a null value.
+
+42. Use `time.Duration` for all time durations. Do not use `int64` or `string`
+    for durations internally.
+
+43. When using `time.Duration` in a struct, use a pointer to `time.Duration` so
+    that you can differentiate between a zero value and a null value.
+
+44. Whenever possible, in argument types and return types, try to use standard
+    library interfaces instead of concrete types. For example, use `io.Reader`
+    instead of `*os.File`. Tailor these to the needs of the specific function or
+    method. Examples:
+    - **`io.Reader`** instead of `*os.File`:
+        - `io.Reader` is a common interface for reading data, which can be
+          implemented by many types, including `*os.File`, `bytes.Buffer`,
+          `strings.Reader`, and network connections like `net.Conn`.
+
+    - **`io.Writer`** instead of `*os.File` or `*bytes.Buffer`:
+        - `io.Writer` is used for writing data. It can be implemented by
+          `*os.File`, `bytes.Buffer`, `net.Conn`, and more.
+
+    - **`io.ReadWriter`** instead of `*os.File`:
+        - `io.ReadWriter` combines `io.Reader` and `io.Writer`. It is often used
+          for types that can both read and write, such as `*os.File` and
+          `net.Conn`.
+
+    - **`io.Closer`** instead of `*os.File` or `*net.Conn`:
+        - `io.Closer` is used for types that need to be closed, including
+          `*os.File`, `net.Conn`, and other resources that require cleanup.
+
+    - **`io.ReadCloser`** instead of `*os.File` or `http.Response.Body`:
+        - `io.ReadCloser` combines `io.Reader` and `io.Closer`, and is commonly
+          used for types like `*os.File` and `http.Response.Body`.
+
+    - **`io.WriteCloser`** instead of `*os.File` or `*gzip.Writer`:
+        - `io.WriteCloser` combines `io.Writer` and `io.Closer`. It is used for
+          types like `*os.File` and `gzip.Writer`.
+
+    - **`io.ReadWriteCloser`** instead of `*os.File` or `*net.TCPConn`:
+        - `io.ReadWriteCloser` combines `io.Reader`, `io.Writer`, and
+          `io.Closer`. Examples include `*os.File` and `net.TCPConn`.
+
+    - **`fmt.Stringer`** instead of implementing a custom `String` method:
+        - `fmt.Stringer` is an interface for types that can convert themselves
+          to a string. Any type that implements the `String() string` method
+          satisfies this interface.
+
+    - **`error`** instead of custom error types:
+        - The `error` interface is used for representing errors. Instead of
+          defining custom error types, you can use the `errors.New` function or
+          the `fmt.Errorf` function to create errors.
+
+    - **`net.Conn`** instead of `*net.TCPConn` or `*net.UDPConn`:
+        - `net.Conn` is a generic network connection interface that can be
+          implemented by TCP, UDP, and other types of network connections.
+
+    - **`http.Handler`** instead of custom HTTP handlers:
+        - `http.Handler` is an interface for handling HTTP requests. Instead of
+          creating custom handler types, you can use types that implement the
+          `ServeHTTP(http.ResponseWriter, *http.Request)` method.
+
+    - **`http.HandlerFunc`** instead of creating a new type:
+        - `http.HandlerFunc` is a type that allows you to use functions as HTTP
+          handlers by implementing the `http.Handler` interface.
+
+    - **`encoding.BinaryMarshaler` and `encoding.BinaryUnmarshaler`** instead of
+      custom marshal/unmarshal methods:
+        - These interfaces are used for binary serialization and
+          deserialization. Implementing these interfaces allows types to be
+          encoded and decoded in a standard way.
+
+    - **`encoding.TextMarshaler` and `encoding.TextUnmarshaler`** instead of
+      custom text marshal/unmarshal methods:
+        - These interfaces are used for text-based serialization and
+          deserialization. They are useful for types that need to be represented
+          as text.
+
+    - **`sort.Interface`** instead of custom sorting logic:
+        - `sort.Interface` is an interface for sorting collections. By
+          implementing the `Len`, `Less`, and `Swap` methods, you can sort any
+          collection using the `sort.Sort` function.
+
+    - **`flag.Value`** instead of custom flag parsing:
+        - `flag.Value` is an interface for defining custom command-line flags.
+          Implementing the `String` and `Set` methods allows you to use custom
+          types with the `flag` package.
+
+45. Avoid using `panic` in library code. Instead, return errors to allow the
+    caller to handle them. Reserve `panic` for truly exceptional conditions.
+
+46. Use `defer` to ensure resources are properly cleaned up, such as closing
+    files or network connections. Place `defer` statements immediately after
+    resource acquisition.
+
+47. When calling a function with `go`, wrap it in an anonymous function to ensure 
+    it runs in the new goroutine context:
+
+    Right:
+
+    ```go
+    go func() {
+        someFunction(arg1, arg2)
+    }()
+    ```
+
+    Wrong:
+
+    ```go
+    go someFunction(arg1, arg2)
+    ```
+
+48. Use `iota` to define enumerations in a type-safe way. This ensures that the
+    constants are properly grouped and reduces the risk of errors.
+
+    Example:
+
+    ```go
+
+    type HandScore int
+
+    const (
+        ScoreHighCard = HandScore(iota * 100_000_000_000)
+        ScorePair
+        ScoreTwoPair
+        ScoreThreeOfAKind
+        ScoreStraight
+        ScoreFlush
+        ScoreFullHouse
+        ScoreFourOfAKind
+        ScoreStraightFlush
+        ScoreRoyalFlush
+    )
+    ```
+
+    Example 2:
+
+    ```go
+    type ByteSize float64
+
+    const (
+        _           = iota // ignore first value by assigning to blank identifier
+        KB ByteSize = 1 << (10 * iota)
+        MB
+        GB
+        TB
+        PB
+        EB
+        ZB
+        YB
+    )
+    ```
+
+49. Do not hardcode large lists. Either isolate lists
+    in their own module/package and write getters, or use a third party
+    library. For example, if you need a list of country codes, you can use
+    [https://github.com/emvi/iso-639-1](https://github.com/emvi/iso-639-1). It is
+    permissible to embed a data file (use `go embed`) in your binary,
+    but make sure you parse it once as a singleton and don't read it from disk
+    every time you need it. Don't use too much memory for this, embedding
+    anything more than perhaps 25MiB (uncompressed) is probably too much.
+    Compress the file before embedding and uncompress during the reading/parsing
+    step.
+
+50. When storing numeric values that represent a number of units, either include
+    the unit in the variable name (e.g. `uptimeSeconds`, `delayMsec`,
+    `coreTemperatureCelsius`), or use a type alias (that includes the unit
+    name), or use a 3p library such as
+    [github.com/alecthomas/units](https://github.com/alecthomas/units) for
+    SI/IEC byte units, or
+    [github.com/bcicen/go-units](https://github.com/bcicen/go-units) for
+    temperatures (and others). The type system is your friend, use it.
+
+51. Once you have a working program, run `go mod tidy` to clean up your `go.mod`
+    and `go.sum` files. Tag a v0.0.1 or v1.0.0. Push your `main` branch and
+    tag(s). Subsequent work should happen on branches so that `main` is "always
+    releasable". "Releasable" in this context means that it builds and functions
+    as expected, and that all tests and linting passes.
+
+# Other Golang Best Practices (Optional)
+
+1.  For any internet-facing http server, set appropriate timeouts and limits to
+    protect against slowloris attacks or huge uploads that can consume server
+    resources without authentication.
+
+    Example to limit request body size:
+
+    ```go
+    package main
+
+     import (
+         "fmt"
+         "net/http"
+     )
+
+     func main() {
+         http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+             // Limit the request body to 10MB
+             r.Body = http.MaxBytesReader(w, r.Body, 10<<20)
+             if err := r.ParseForm(); err != nil {
+                 http.Error(w, "Request body too large", http.StatusRequestEntityTooLarge)
+                 return
+             }
+             fmt.Fprintf(w, "Hello, World!")
+         })
+
+         http.ListenAndServe(":8080", nil)
+     }
+    ```
+
+    Example to set appropriate timeouts:
+
+    ```go
+    package main
+
+    import (
+        "net/http"
+        "time"
+    )
+
+    func main() {
+        server := &http.Server{
+            Addr:         ":8080",
+            ReadTimeout:  5 * time.Second,
+            WriteTimeout: 10 * time.Second,
+            Handler:      http.DefaultServeMux,
+        }
+
+        http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+            fmt.Fprintf(w, "Hello, World!")
+        })
+
+        server.ListenAndServe()
+    }
+    ```
+
+2.  When passing channels to goroutines, use read-only (`<-chan`) or write-only
+    (`chan<-`) channels to communicate the direction of data flow clearly.
+
+3.  Use `io.MultiReader` to concatenate multiple readers and `io.MultiWriter` to
+    duplicate writes to multiple writers. This can simplify the handling of
+    multiple data sources or destinations.
+
+4.  For simple counters and flags, use the `sync/atomic` package to avoid the
+    overhead of mutexes.
+
+5.  When using mutexes, minimize the scope of locking to reduce contention and
+    potential deadlocks. Prefer to lock only the critical sections of code and try
+    to encapsulate it in its own method. Acquire
+    the lock in the first function line, defer release of the lock as the
+    second line, and lines 3-5 should perform the task. Keep it short. Avoid using mutexes in the middle of a function. In short, build atomic functions.
+
+6.  Design types to be immutable, to avoid issues with concurrent access.
+
+7.  Global state can lead to unpredictable behavior and makes the code harder to
+    test. Use dependency injection to manage state.
+
+8.  Avoid using `init` functions unless absolutely necessary. Tthey can lead to
+    unpredictable initialization order and make code harder to understand.
+
+9.  Provide comments for all public interfaces explaining what they do and how
+    they should be used, to help other developers understand the intended use.
+
+10. Be mindful of resource leaks when using `time.Timer` and `time.Ticker`.
+    Always stop them when they are no longer needed.
+
+11. Use `sync.Pool` to manage a pool of reusable objects, which can help reduce
+    GC overhead and improve performance in high-throughput scenarios.
+
+12. Avoid using large buffer sizes for channels. Unbounded channels can lead to
+    memory leaks. Use appropriate buffer sizes based on the application's needs.
+
+13. Always handle the case where a channel might be closed. This prevents panic
+    and ensures graceful shutdowns.
+
+14. For small structs, use value receivers to avoid unnecessary heap allocations.
+    Use pointer receivers for large structs or when mutating the receiver.
+
+15. Only use goroutines when necessary. Excessive goroutines can lead to high
+    memory consumption and increased complexity.
+
+16. Use `sync.Cond` for more complex synchronization needs that cannot be met
+    with simple mutexes and channels.
+
+17. Reflection is powerful but should be used sparingly as it can lead to code
+    that is hard to understand and maintain. Prefer type-safe solutions.
+
+18. Avoid storing large or complex data in context. Context should be used for
+    request-scoped values like deadlines, cancellation signals, and
+    authentication tokens.
+
+19. Use `runtime.Callers` and `runtime.CallersFrames` to capture stack traces for
+    debugging and logging purposes.
+
+20. Use the `testing.TB` interface to write helper functions that can be used
+    with both `*testing.T` and `*testing.B`.
+
+21. Use struct embedding to reuse code across multiple structs. This form of
+    composition simplifies code reuse.
+
+22. Prefer defining explicit interfaces in your packages rather than relying on
+    implicit interfaces, for clarity.
+
+# Author
+
+[@sjdev](https://sjdev.co)
+&lt;[sj@sjdev.co(mailto:sj@sjdev.berlin)&gt;
+
+# License
+
+MIT. See [LICENSE](../LICENSE).

LLM_DEV_PROMPTS/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sjdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LLM_DEV_PROMPTS/Makefile

@@ -0,0 +1,31 @@
+.PHONY: test lint fmt fmt-check check docker hooks
+
+# flags are repeated here (also in .prettierrc) so this Makefile works
+# standalone when copied as a template
+PRETTIER := yarn run prettier
+
+test:
+	@echo "No tests defined."
+
+lint:
+	@echo "Linting markdown files..."
+	@$(PRETTIER) --check '**/*.md' --tab-width 4 --prose-wrap always
+
+fmt:
+	@$(PRETTIER) --write '**/*.md' --tab-width 4 --prose-wrap always
+
+fmt-check:
+	@$(PRETTIER) --check '**/*.md' --tab-width 4 --prose-wrap always
+
+check: test lint fmt-check
+
+docker:
+	docker build -t prompts .
+
+hooks:
+	@printf '#!/bin/sh\nset -e\n' > .git/hooks/pre-commit
+	@if [ -f go.mod ]; then \
+		printf 'go mod tidy\ngo fmt ./...\ngit diff --exit-code -- go.mod go.sum || { echo "go mod tidy changed files; please stage and retry"; exit 1; }\n' >> .git/hooks/pre-commit; \
+	fi
+	@printf 'make check\n' >> .git/hooks/pre-commit
+	@chmod +x .git/hooks/pre-commit

LLM_DEV_PROMPTS/NODEJS PROJECTS/CODE_STYLEGUIDE_JS.md

@@ -0,0 +1,81 @@
+---
+title: Code Styleguide — JavaScript
+last_modified: 2026-02-22
+---
+
+1. Use `const` for all declarations, unless you need to reassign, then use `let`. Never use
+   `var`.
+
+2. Indentation: Use 2 spaces.  Do not use tabs.
+
+3. Semicolons shoudl be used at the end of statements.
+
+4. Quotes: Prefer single quotes for strings, unless working with JSON or needing to separate object strings.
+
+5. Limit lines to approximately 80 characters for better readability.
+
+6. Brace Placement: Place the opening brace on the same line as the statement (e.g., if (true) {).
+
+7. Naming Conventions:
+   
+   Variables, properties, and functions use lowerCamelCase.
+   Class names use UpperCamelCase (PascalCase).
+   Constants use UPPERCASE_WITH_UNDERSCORES. 
+
+8. Equality: Always use the strict equality operator (===) over the abstract equality operator (==).
+
+9. Use npm for package management, avoid using yarn.
+
+10. Use nvm and install/select the most current LTS Node version.
+
+11. Use `prettier` for code formatting, with four spaces for indentation.
+
+12. At a minimum, both `npm run test`/`npm run build` should work (complete the appropriate scripts in `package.json`). However, prefer `make test` and `make build` instead —
+
+13. The Makefile is authoritative on how to interact with the repo. See
+   [Repository Policies](https://github.com/kjannette/LLM_DEV_PROMPTS/blob/master/REPO_POLICIES.md) for details.
+
+14. Use UNIX-style newlines (\n), and a newline character as the last character of a file. Windows-style newlines (\r\n) are forbidden inside any Node/JS repository.
+
+15. Declare one variable per statement:
+
+**Correct:**
+
+```
+   const keys   = ['foo', 'bar'];
+   const values = [23, 42];
+   const object = {};
+```
+**Incorrect:**
+
+```
+const keys = ['foo', 'bar'],
+      values = [23, 42],
+      object = {},
+```
+
+16.  Name closures in order to produce better stack traces, heap and cpu profiles.
+
+**Correct:**
+
+```
+req.on('end', function onEnd() {
+  console.log('winning');
+});
+```
+**Incorrect:**
+
+```
+req.on('end', function() {
+  console.log('losing');
+});
+```
+
+# Author
+
+[@sjDev](https://sjdev.co)
+<[sj@sjdev.co](mailto:sj@sjdev.co)>
+
+# License
+
+MIT. See [LICENSE](../LICENSE).

LLM_DEV_PROMPTS/NODEJS PROJECTS/NODE_BACKEND_ARCH_BASICS.md

@@ -0,0 +1,30 @@
+---
+title: Node Backend Architectural Basic Principals
+last_modified: 2026-03-02
+---
+
+1. Separate concerns  into distinct layers. 
+
+2. Adhering to the above pricinciple makes c ode more extensible, testable and maintainable. Group around functionality, adhering to the following structure on the backend:
+
+ a. **Routes/Controllers:** Handle API endpoints and process the request/response cycle. Controllers should be kept lean, delegating business logic to the service layer.
+
+ b. **Services/Business Logic:** Contain the core application logic and domain rules. This layer orchestrates interactions between other components.
+
+ c.  **Models/Data Access:** Interact with the database (using ORMs like Mongoose or Sequelize). Abstract database logic into repositories for reusability.
+
+ d. **Middleware:** Used for cross-cutting concerns such as cors, authentication, logging, and error handling.
+
+3. Modularity: Break code into the smallest reusable modules that make logical sense.  Each discreet class or method should have a single responsibility.
+
+4. Objects should depend on abstractions, not concretions. High-level modules contain the core business logic or application-specific behavior.
+Lower-level modules deal with implementation details, such as interacting with a database, file system, or external APIs.
+
+# Author
+
+[@sjDev](https://sjdev.co)
+<[sj@sjdev.co](mailto:sj@sjdev.co)>
+
+# License
+
+MIT. See [LICENSE](../LICENSE).

LLM_DEV_PROMPTS/PYTHON PROJECTS/CODE_STYLEGUIDE_PYTHON.md

@@ -0,0 +1,54 @@
+---
+title: Code Styleguide — Python
+last_modified: 2026-02-22
+---
+
+1. Standard Project Layout.  Use the src/ layout to prevent accidental imports from the root and ensure your project behaves like an installed package:
+
+my_project/
+├── pyproject.toml      # Modern tool & dependency configuration
+├── README.md           # Instructions for humans
+├── LICENSE             # Usage rights
+├── .gitignore          # Exclude venv/, __pycache__/, .env
+├── src/
+│   └── my_project/     # Main package
+│       ├── __init__.py
+│       ├── main.py     # Minimal entry point logic
+│       └── core.py     # Business logic
+├── tests/              # Mirror src structure for testing
+└── docs/               # Technical documentation
+
+2. Virtual Environments: Always isolate project dependencies using venv or pyenv to avoid conflicts with system-wide packages.
+
+3. Adhere to PEP 8: Use 4 spaces for indentation (no tabs), limit lines to 79 characters, and use two blank lines between top-level functions.
+
+4. Put code in functions. If you are writing a script, put the script in a
+function called `main` and call `main()` at the end of the script using the
+standard invocation:
+
+    ```python
+    if __name__ == "__main__":
+        main()
+    ```
+5. Keep main.py Boring: The entry point should only orchestrate (load config, start app). Heavy business logic should live in specialized modules.
+
+6. Config Isolation: Never hardcode secrets or database URLs. Use a .env file with libraries like python-dotenv or Pydantic Settings.
+
+7. Logging over Printing: Use Python’s built-in logging module to track errors and application state in production.
+
+8. Test-First: Treat your tests/ directory as first-class code. Use pytest for its powerful features and simple syntax.
+
+9. Naming Conventions: Use snake_case for functions and variables, PascalCase for classes, and UPPER_CASE for constants.
+
+10. pyproject.toml: Use this as the single source of truth for project metadata and tool configurations (replaces setup.py).
+
+11. Modular Design: Group code by domain (e.g., /users, /payments) rather than function (e.g., utils.py) to maintain separation of concerns.
+
+# Author
+
+[@sjdev](https://sjdev.co)
+<[sj@sjdev.co](mailto:sj@sjdev.berlin)>
+
+# License
+
+MIT. See [LICENSE](../LICENSE).

LLM_DEV_PROMPTS/README.md

@@ -0,0 +1,139 @@
+# LLM Development Prompts
+
+An MIT-licensed collection of LLM prompts by [@sjdev](https://sjdev.co), intended for use in bootstrapping new projects or building out new features in existing codebases.
+
+The prompts set forth best practices and procedural directives that must be followed in architecture and development. Think of this repo as akin to the Chicago Manual of Style, AP Stylebook (for journalism), or The ALWD Guide to Legal Citation.
+
+The prompts include 1) general repository development standards and 2) language and framework-specific development directives, intended to be reviewed by the code-building model at the outset work and followed throughout the work’s progress.  For example, the Javascript code styleguide sets forth the simple directive: “[u]se const for all declarations, unless you need to reassign, then use let. Never use var.”  
+
+These prompts are a work in progress.  I add to them as I work on new projects in new languages and frameworks, and I am also still in the process of memorializing prompts relating to languages and frameworks I have used for many years.
+
+# Usage - generally
+
+Imagine the scenario: you, as a developer, are tasked with adding a new feature to an existing codebase, with maximum automation via LLM code generation.  At the outset, before adressing the substantive implementation, you would run the following prompt (discussed in greater detail below):
+
+Read $TD/prompts/REPO_POLICIES.md and $TD/prompts/EXISTING_REPO_CHECKLIST.md, then bring this repo up to those
+standards. Your scope is repo scaffolding and policy compliance: Makefile, Dockerfile, .dockerignore, .gitignore, .editorconfig, CI
+workflow, README sections, LICENSE, REPO_POLICIES.md, and any language-specific config files (.golangci.yml, .prettierrc, etc.).
+
+## Quick Start - optional scripts for cli agent
+
+### Existing Repo
+
+Run from within the repo you want to bring up to standard. Clone the prompts repo once, then run both commands in order.
+
+```bash
+export TD="$(mktemp -d)"
+git clone --depth 1 https://github.com/kjannette/LLM_DEV_PROMPTS.git "$TD"
+```
+
+**Repository structure and policies:**
+
+```bash
+claude "Read $TD/prompts/REPO_POLICIES.md and
+$TD/prompts/EXISTING_REPO_CHECKLIST.md, then bring this repo up to those
+standards. Your scope is repo scaffolding and policy compliance:
+Makefile, Dockerfile, .dockerignore, .gitignore, .editorconfig, CI
+workflow, README sections, LICENSE, REPO_POLICIES.md, and any
+language-specific config files (.golangci.yml, .prettierrc, etc.).
+You must also run the formatter (make fmt) and fix any linter errors
+(make lint) so that make check passes — this will touch source code,
+but do not restructure, refactor, or rewrite any application logic.
+Follow the policies yourself: work on a feature branch, never git add -A,
+and make each logical change a separate commit (e.g. one commit for
+formatting, one for linter fixes, one for README updates, one for each
+new repo file added, etc.)."
+```
+
+**Code style and conventions:**
+
+```bash
+claude "Read $TD/prompts/CODE_STYLEGUIDE.md and whichever
+language-specific styleguides in $TD/prompts/ apply to this repo
+(CODE_STYLEGUIDE_GO.md, CODE_STYLEGUIDE_JS.md, CODE_STYLEGUIDE_PYTHON.md,
+GO_HTTP_SERVER_CONVENTIONS.md). Then review the application code in this
+repo and bring it into compliance with those coding standards. Your scope
+is application code structure and style: naming, patterns, error
+handling, project layout, and conventions described in the styleguides.
+Do not modify repo scaffolding (Makefile, Dockerfile, CI workflow,
+.gitignore, .editorconfig, etc.) — only application code. Work on a
+feature branch, never git add -A, and make each logical change a
+separate commit."
+```
+
+### New Repo
+
+Run from inside the directory where you want to create a new repo. Clone the
+prompts repo once, then run both commands in order.
+
+```bash
+export TD="$(mktemp -d)"
+git clone --depth 1 https://github.com/kjannette/LLM_DEV_PROMPTS.git "$TD"
+```
+
+**Repository scaffolding:**
+
+```bash
+claude "Read $TD/prompts/REPO_POLICIES.md and
+$TD/prompts/NEW_REPO_CHECKLIST.md, then set up this new repo according
+to those standards. Your scope is repo structure and required files:
+README.md, LICENSE, REPO_POLICIES.md, Makefile, Dockerfile, .dockerignore,
+.gitignore, .editorconfig, CI workflow, and language-specific config.
+Run the formatter (make fmt) and fix any linter errors (make lint) so
+that make check passes — this will touch source code, but do not
+restructure, refactor, or rewrite any application logic. Follow the
+policies yourself: work on a feature branch, never git add -A, and make
+each logical change a separate commit (e.g. one commit for formatting,
+one for linter fixes, one for README, one for each new repo file, etc.)."
+```
+
+**Code style and conventions:**
+
+```bash
+claude "Read $TD/prompts/CODE_STYLEGUIDE.md and whichever
+language-specific styleguides in $TD/prompts/ apply to this repo
+(CODE_STYLEGUIDE_GO.md, CODE_STYLEGUIDE_JS.md, CODE_STYLEGUIDE_PYTHON.md,
+GO_HTTP_SERVER_CONVENTIONS.md). Then review the application code in this
+repo and bring it into compliance with those coding standards. Your scope
+is application code structure and style: naming, patterns, error
+handling, project layout, and conventions described in the styleguides.
+Do not modify repo scaffolding (Makefile, Dockerfile, CI workflow,
+.gitignore, .editorconfig, etc.) — only application code. Work on a
+feature branch, never git add -A, and make each logical change a
+separate commit."
+```
+
+## Getting Started
+
+```bash
+git clone https://github.com/kjannette/LLM_DEV_PROMPTS.git
+cd prompts
+```
+
+Prompts are stored as Markdown files in `prompts/`. Copy or reference them as
+needed in your projects.
+
+## Rationale
+
+LLM prompts, especially development policies, benefit from version control and a
+single authoritative source. This repo provides a central place to maintain,
+share, and evolve prompts across projects.
+
+## Design
+
+The repository is a collection of Markdown files organized in the `prompts/`
+subdirectory. Each file contains one or more related prompts or policy
+documents. There is no build step or runtime component; the prompts are consumed
+by copying them into other projects or referencing them directly.
+
+## TODO
+
+- Add more prompt templates for common development tasks
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Author
+
+[@sjdev](https://sjdev.co)

LLM_DEV_PROMPTS/TYPESCRIPT PROJECTS/CODE_STYLEGUIDE_TYPESCRIPT.md

@@ -0,0 +1,214 @@
+1. General Types
+
+Don't ever use the types Number, String, Boolean, Symbol, or Object These types refer to non-primitive boxed objects that are almost never used appropriately in JavaScript code.
+
+/* WRONG */
+function reverse(s: String): String;
+
+Do use the types number, string, boolean, and symbol.
+
+/* OK */
+function reverse(s: string): string;
+
+Instead of Object, use the non-primitive object type.
+
+2. Use const and let
+
+JavaScript first searches to see if a variable exists locally, then searches progressively in higher levels of scope until global variables. var is function scope, but, let and const are block scope. 
+
+Using let and const where appropriate makes the intention of the declarations clearer. 
+
+It will also help in identifying issues when a value is reassigned to a constant accidentally by throwing a compile time error. 
+
+Use a linter that automates checking and fixing this so that changing let to const doesn't become a delay in code review.
+
+3. Use === instead of ==
+
+JavaScript utilizes two different kinds of equality operators: === | !== and == | !=. 
+
+It is considered best practice to always use the former set when comparing. 
+
+If two operands are of the same type and value, then === produces true and !== produces false. 
+
+However, when working with == and !=, we'll run into issues when working with different types. In these cases, they'll try to coerce the values, unsuccessfully.
+
+4. Use the fastest way to loop arrays
+
+There are many ways to loop through array. The first way is a for loop.  Other ways include the for...of loop, the forEach method for arrays, map, filter, and others. There is also the while loop. 
+
+The for loop is the fastest way. Caching the length makes the loop perform better. Some browser engines have optimized the for loop without manually caching the length property. The forEach is slower than the for loop, so it's probably better to avoid it, especially for large arrays. However, unless we are desperate for performance at the code level (which is rare), make it readable. For example, we can use the for loop in server-side applications and the array methods in client-side applications, because, in general, we don't have expensive operations on the client-side.
+
+5. Prefer array methods
+
+It is recommended to use a functional approach without intermediate variables. The base JavaScript for loop can be more performant in some browsers but the benefit can be measured only by iterating over millions of items. It is the job of compiler and runtime to remove the penalty of using new array methods. 
+
+6. Do not trust any data - Validate
+
+Make sure that all the data that goes into our system is clean and exactly what we need. This is most important on the back end when writing out parameters retrieved from the URL. 
+
+The same applies to forms that validate only on the client side. Another very insecure practice is to read information from the DOM and use it without validation.
+
+7. Generics
+
+Don't ever have a generic type which doesn't use its type parameter.
+
+8. Any
+
+Don't use any as a type unless you are in the process of migrating a JavaScript project to TypeScript. The compiler effectively treats any as "please turn off type checking for this thing". It is similar to putting an @ts-ignore comment around every usage of the variable. This can be very helpful when you are first migrating a JavaScript project to TypeScript as you can set the type for stuff you haven't migrated yet as any, but in a full TypeScript project you are disabling type checking for any parts of your program that use it.
+In cases where you don't know what type you want to accept, or when you want to accept anything because you will be blindly passing it through without interacting with it, you can use unknown.
+
+9. Strict configuration
+
+The stricter configuration is mandatory. Otherwise, types will be too permissive, and it is what we are trying to avoid as much as possible with Typescript.
+
+{
+  "forceConsistentCasingInFileNames": true,
+  "noImplicitReturns": true,
+  "strict": true,
+  "noUnusedLocals": true,
+}
+
+The most important one here is the strict flag which actually covers four other flags: noImplicitAny, noImplicitThis, alwaysStrict and strictNullChecks.
+
+10. Callback Types - Return Types of Callbacks
+
+Don't use the return type any for callbacks whose value will be ignored:
+/* WRONG */
+function fn(x: () => any) {
+ x();
+}
+
+Do use the return type void for callbacks whose value will be ignored:
+/* OK */
+function fn(x: () => void) {
+ x();
+}
+
+Why: Using void is safer because it prevents you from accidentally using the return value of x in an unchecked way:
+function fn(x: () => void) {
+ var k = x(); // oops! meant to do something else
+ k.doSomething(); // error, but would be OK if the return type had been 'any'
+}
+
+11. Optional Parameters in Callbacks
+
+Don't use optional parameters in callbacks unless you really mean it:
+
+/* WRONG */
+interface Fetcher {
+ getObject(done: (data: unknown, elapsedTime?: number) => void): void;
+}
+
+This has a very specific meaning: the done callback might be invoked with 1 argument or might be invoked with 2 arguments. The author probably intended to say that the callback might not care about the elapsedTime parameter, but there's no need to make the parameter optional to accomplish this — it's always legal to provide a callback that accepts fewer arguments.
+
+Do write callback parameters as non-optional:
+/* OK */
+interface Fetcher {
+ getObject(done: (data: unknown, elapsedTime: number) => void): void;
+}
+
+12. Overloads and Callbacks
+
+Don't write separate overloads that differ only on callback arity:
+
+/* WRONG */
+declare function beforeAll(action: () => void, timeout?: number): void;
+declare function beforeAll(
+ action: (done: DoneFn) => void,
+ timeout?: number
+): void;
+
+Do write a single overload using the maximum arity:
+
+/* OK */
+declare function beforeAll(
+ action: (done: DoneFn) => void,
+ timeout?: number
+): void;
+
+Why: It's always legal for a callback to disregard a parameter, so there's no need for the shorter overload. Providing a shorter callback first allows incorrectly-typed functions to be passed in because they match the first overload.
+
+13. Function Overloads
+
+13.1 Ordering
+
+Don't put more general overloads before more specific overloads:
+/* WRONG */
+declare function fn(x: unknown): unknown;
+declare function fn(x: HTMLElement): number;
+declare function fn(x: HTMLDivElement): string;
+var myElem: HTMLDivElement;
+var x = fn(myElem); // x: unknown, wat?
+
+Do sort overloads by putting the more general signatures after more specific signatures:
+
+/* OK */
+declare function fn(x: HTMLDivElement): string;
+declare function fn(x: HTMLElement): number;
+declare function fn(x: unknown): unknown;
+var myElem: HTMLDivElement;
+var x = fn(myElem); // x: string, :)
+
+Why: TypeScript chooses the first matching overload when resolving function calls. When an earlier overload is "more general" than a later one, the later one is effectively hidden and cannot be called.
+
+13.2 Use Optional Parameters
+
+Don't write several overloads that differ only in trailing parameters:
+
+/* WRONG */
+interface Example {
+ diff(one: string): number;
+ diff(one: string, two: string): number;
+ diff(one: string, two: string, three: boolean): number;
+}
+
+Do use optional parameters whenever possible:
+
+/* OK */
+interface Example {
+ diff(one: string, two?: string, three?: boolean): number;
+}
+
+Note that this collapsing should only occur when all overloads have the same return type.
+
+Why: This is important for two reasons.
+TypeScript resolves signature compatibility by seeing if any signature of the target can be invoked with the arguments of the source, and extraneous arguments are allowed. This code, for example, exposes a bug only when the signature is correctly written using optional parameters:
+function fn(x: (a: string, b: number, c: number) => void) {}
+var x: Example;
+// When written with overloads, OK -- used first overload
+// When written with optionals, correctly an error
+fn(x.diff);
+
+The second reason is when a consumer uses the "strict null checking" feature of TypeScript. 
+
+Because unspecified parameters appear as undefined in JavaScript, it's usually fine to pass an explicit undefined to a function with optional arguments. This code, for example, should be OK under strict nulls:
+var x: Example;
+// When written with overloads, incorrectly an error because of passing 'undefined' to 'string'
+// When written with optionals, correctly OK
+x.diff("something", true ? undefined : "hour");
+
+13. Use Union Types
+
+Don't write overloads that differ by type in only one argument position:
+/* WRONG */
+interface Moment {
+ utcOffset(): number;
+ utcOffset(b: number): Moment;
+ utcOffset(b: string): Moment;
+}
+
+Do use union types whenever possible:
+/* OK */
+interface Moment {
+ utcOffset(): number;
+ utcOffset(b: number | string): Moment;
+}
+Note that we didn't make b optional here because the return types of the signatures differ.
+❔ Why: This is important for people who are "passing through" a value to your function:
+function fn(x: string): Moment;
+function fn(x: number): Moment;
+function fn(x: number | string) {
+ // When written with separate overloads, incorrectly an error
+ // When written with union types, correctly OK
+ return moment().utcOffset(x);
+}

LLM_DEV_PROMPTS/package.json

@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "prettier": "3.8.1"
+  }
+}

Makefile

@@ -2,7 +2,7 @@
         test-go test-js lint-go lint-js fmt-go fmt-js fmt-check-go fmt-check-js \
         build-go build-js
 
-GODIR    := backend-go
+GODIR    := backend
 JSDIR    := frontend
 PRETTIER := $(JSDIR)/node_modules/.bin/prettier
 

README.md

@@ -1,9 +1,9 @@
 # Koin Ping
+A lightweight on-chain monitoring and alerting system designed to give users situational awareness over blockchain addresses they care about.
 
-Koin Ping is an MIT-licensed blockchain monitoring system by Steven Jannette
-that polls Ethereum addresses for on-chain activity and delivers real-time
-alerts to users via a Go REST API backend and a React single-page application
-frontend.
+# Overview
+
+Koin Ping observes on-chain activity and notifies users when predefined conditions are met. It does not execute transactions, manage wallets, or speculate on prices.
 
 ## Getting Started
 
@@ -28,8 +28,8 @@ make hooks
 cd frontend && npm install && cd ..
 
 # Copy and fill in environment variables
-cp backend-go/.env.example backend-go/.env
-# edit backend-go/.env with your DATABASE_URL, FIREBASE_PROJECT_ID, ETH_RPC_URL
+cp backend/.env.example backend/.env
+# edit backend/.env with your DATABASE_URL, FIREBASE_PROJECT_ID, ETH_RPC_URL
 
 # Run checks (requires golangci-lint)
 make check
@@ -38,23 +38,23 @@ make check
 make run
 
 # Start the poller (separate terminal)
-cd backend-go && go run ./cmd/poller
+cd backend && go run ./cmd/poller
 
 # Start the frontend dev server (separate terminal)
 cd frontend && npm run dev
 ```
 
 The API listens on `http://localhost:3001` and the frontend on
-`http://localhost:3000` by default.
+`http://localhost:3000` by default for development.
 
 ## Rationale
 
-Crypto users who hold or actively monitor addresses need a lightweight, reliable
-way to know when on-chain activity occurs without polling block explorers
-manually. Koin Ping fills that gap: it watches a set of Ethereum addresses,
-evaluates configurable alert rules (incoming transactions, outgoing
-transactions, large transfers, balance thresholds), and notifies the user
-through Discord webhooks.
+Crypto users may actively monitor addresses with webhooks integrating popular 
+messaging platforms: Discord, Slack, Telegram.
+This lightweight, reliable framework makes instant awareness of on-chain 
+activity trivial, without polling block explorers manually. Koin Ping watches 
+addresses, evaluates configurable alert rules (incoming transactions, outgoing 
+transactions, "large" transfers, balance thresholds), and sends notifications.
 
 ## Design
 
@@ -63,7 +63,7 @@ frontend:
 
 ```
 koin_ping_0.2.0/
-├── backend-go/                # Go monorepo root
+├── backend/                # Go monorepo root
 │   ├── cmd/api/               # HTTP REST API server
 │   ├── cmd/poller/            # Blockchain polling daemon
 │   └── internal/
@@ -99,19 +99,51 @@ to the database, and dispatches Discord notifications.
 Firebase, communicates with the API via fetch, and renders the address/alert
 management UI.
 
-## TODO
+## Setting Up Your Alert Platforms
 
-- [ ] Switch frontend package manager from npm to yarn (per repo policy)
-- [ ] Rename `go.mod` module path from `github.com/kjannette/koin-ping` to
-      `sneak.berlin/go/koin-ping` (per repo policy)
-- [ ] Move database migrations to `internal/db/migrations/` and embed them in
-      the binary
-- [ ] Pin all Docker base images by `@sha256` in Dockerfile
-- [ ] Install `golangci-lint` locally and pass `make lint`
-- [ ] Add vitest unit tests for the React frontend
-- [ ] Add a `make db-reset` / `make migrate` target for schema management
-- [ ] Set HTTP server read/write timeouts (currently unbounded)
-- [ ] Replace `log.Printf` calls with structured `log/slog`
+Koin Ping can send real-time alerts to **Telegram**, **Discord**, **Slack**, and **Email**. Each channel is configured per-user through the **Notification Settings** panel on the Alerts page.
+
+Below are step-by-step guides for setting up each platform.
+
+---
+
+### Telegram
+
+To receive alerts via Telegram, you need to create a bot and get your chat ID.
+
+#### 1. Create a Telegram Bot
+
+1. Open Telegram and search for **@BotFather** (look for the blue verified checkmark).
+2. Open the conversation with BotFather and send: `/newbot`
+3. BotFather will ask for a **display name** — enter something like `Koin Ping Alerts`.
+4. BotFather will ask for a **username** — it must end in `bot`, e.g. `MyKoinPingBot`.
+5. BotFather will reply with your **Bot Token** — a string that looks like `123456789:ABCdefGHIjklMNOpqrSTUvwxYZ`. Copy it.
+
+#### 2. Get Your Chat ID
+
+1. In Telegram, search for the bot username you just created and open the chat.
+2. Tap **Start** or send any message (e.g. `hello`).
+3. Open the following URL in your browser, replacing `YOUR_BOT_TOKEN` with the token from step 1:
+
+   ```
+   https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
+   ```
+
+4. In the JSON response, find the `"chat"` object — the `"id"` field is your **Chat ID** (a numeric value).
+
+   > **Tip:** If the `'result"` array is empty, make sure you sent a message to your bot first, then refresh the page.
+
+#### 3. Save in Koin Ping
+
+1. Go to the **Alerts** page in Koin Ping.
+2. In the **Notification Settings** panel, find the **Telegram** section.
+3. Paste your **Bot Token** and **Chat ID** into the corresponding fields.
+4. Click **Save Settings**.
+5. Click **Test All Channels** to verify — you should receive a test message from your bot in Telegram.
+
+---
+
+*Guides for Discord, Slack, and Email coming soon.*
 
 ## License
 
@@ -120,3 +152,5 @@ MIT. See [LICENSE](LICENSE).
 ## Author
 
 Steven Jannette
+
+

backend-go/.env.example

@@ -1,16 +0,0 @@
-# Server
-PORT=3001
-API_BASE_PATH=/v1
-NODE_ENV=development
-
-# Database
-DATABASE_URL=postgresql://user:password@localhost:5432/koin_ping
-
-# Ethereum JSON-RPC
-ETH_RPC_URL=https://mainnet.infura.io/v3/YOUR-PROJECT-ID
-
-# Polling interval (ms, minimum 1000)
-POLL_INTERVAL_MS=60000
-
-# Firebase
-FIREBASE_PROJECT_ID=koin-ping

backend-go/README.md

@@ -1,7 +0,0 @@
-Start DB:
-
-brew services start postgresql@15
-
-Run Backend:
-
-cd /Users/kjannette/workspace/koin_ping/backend-go go run ./cmd/api

backend-go/cmd/api/main.go

@@ -1,125 +0,0 @@
-// Package main is the entry point for the API server.
-package main
-
-import (
-	"fmt"
-	"log"
-	"net/http"
-	"time"
-
-	"github.com/joho/godotenv"
-	"github.com/kjannette/koin-ping/backend-go/internal/config"
-	"github.com/kjannette/koin-ping/backend-go/internal/database"
-	"github.com/kjannette/koin-ping/backend-go/internal/firebase"
-	"github.com/kjannette/koin-ping/backend-go/internal/handlers"
-	"github.com/kjannette/koin-ping/backend-go/internal/middleware"
-	"github.com/kjannette/koin-ping/backend-go/internal/models"
-)
-
-const (
-	// serverReadTimeoutSeconds is the maximum duration to read a request.
-	serverReadTimeoutSeconds = 5
-	// serverWriteTimeoutSeconds is the maximum duration to write a response.
-	serverWriteTimeoutSeconds = 10
-)
-
-//nolint:funlen
-func main() {
-	_ = godotenv.Load() // .env is optional; env vars can also be set externally
-
-	cfg, err := config.Load()
-	if err != nil {
-		log.Fatalf("Failed to load config: %v", err)
-	}
-
-	pool, err := database.Connect(cfg.DSN())
-	if err != nil {
-		log.Fatalf("Failed to connect to database: %v", err)
-	}
-
-	if err := firebase.Init(cfg.FirebaseProjectID); err != nil {
-		log.Fatalf("Failed to initialize Firebase: %v", err)
-	}
-
-	defer database.Close()
-
-	addressModel := models.NewAddressModel(pool)
-	alertRuleModel := models.NewAlertRuleModel(pool)
-	alertEventModel := models.NewAlertEventModel(pool)
-	notifConfigModel := models.NewNotificationConfigModel(pool)
-
-	addressHandler := handlers.NewAddressHandler(addressModel)
-	alertRuleHandler := handlers.NewAlertRuleHandler(alertRuleModel, addressModel)
-	alertEventHandler := handlers.NewAlertEventHandler(alertEventModel)
-	notifConfigHandler := handlers.NewNotificationConfigHandler(notifConfigModel)
-
-	mux := http.NewServeMux()
-	b := cfg.APIBasePath // e.g. "/v1"
-
-	// Public routes
-	mux.HandleFunc("GET "+b+"/health", handlers.HealthCheck)
-	mux.HandleFunc("GET "+b+"/status", handlers.SystemStatus)
-
-	// Authenticated routes — addresses
-	mux.Handle("POST "+b+"/addresses",
-		middleware.Authenticate(http.HandlerFunc(addressHandler.Create)))
-	mux.Handle("GET "+b+"/addresses",
-		middleware.Authenticate(http.HandlerFunc(addressHandler.List)))
-	mux.Handle("DELETE "+b+"/addresses/{addressId}",
-		middleware.Authenticate(http.HandlerFunc(addressHandler.Remove)))
-
-	// Authenticated routes — alert rules
-	mux.Handle("POST "+b+"/addresses/{addressId}/alerts",
-		middleware.Authenticate(http.HandlerFunc(alertRuleHandler.Create)))
-	mux.Handle("GET "+b+"/addresses/{addressId}/alerts",
-		middleware.Authenticate(http.HandlerFunc(alertRuleHandler.ListByAddress)))
-	mux.Handle("PATCH "+b+"/alerts/{alertId}",
-		middleware.Authenticate(http.HandlerFunc(alertRuleHandler.UpdateStatus)))
-	mux.Handle("DELETE "+b+"/alerts/{alertId}",
-		middleware.Authenticate(http.HandlerFunc(alertRuleHandler.Remove)))
-
-	// Authenticated routes — alert events
-	mux.Handle("GET "+b+"/alert-events",
-		middleware.Authenticate(http.HandlerFunc(alertEventHandler.List)))
-
-	// Authenticated routes — notification config
-	mux.Handle("GET "+b+"/notification-config",
-		middleware.Authenticate(http.HandlerFunc(notifConfigHandler.GetConfig)))
-	mux.Handle("PUT "+b+"/notification-config",
-		middleware.Authenticate(http.HandlerFunc(notifConfigHandler.UpdateConfig)))
-	mux.Handle("DELETE "+b+"/notification-config",
-		middleware.Authenticate(http.HandlerFunc(notifConfigHandler.DeleteConfig)))
-
-	handler := corsMiddleware(mux)
-
-	addr := fmt.Sprintf(":%d", cfg.Port)
-	log.Printf("Server running on port %d", cfg.Port)
-	log.Printf("API base path: %s", cfg.APIBasePath)
-	log.Printf("Environment: %s", cfg.NodeEnv)
-
-	server := &http.Server{
-		Addr:         addr,
-		Handler:      handler,
-		ReadTimeout:  serverReadTimeoutSeconds * time.Second,
-		WriteTimeout: serverWriteTimeoutSeconds * time.Second,
-	}
-	if err := server.ListenAndServe(); err != nil {
-		log.Fatalf("Server failed: %v", err)
-	}
-}
-
-func corsMiddleware(next http.Handler) http.Handler {
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Access-Control-Allow-Origin", "*")
-		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS")
-		w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
-
-		if r.Method == http.MethodOptions {
-			w.WriteHeader(http.StatusNoContent)
-
-			return
-		}
-
-		next.ServeHTTP(w, r)
-	})
-}

backend-go/internal/config/config.go

@@ -1,94 +0,0 @@
-//loads environment-based configuration.
-package config
-
-import (
-	"fmt"
-	"os"
-	"strconv"
-	"strings"
-)
-
-const (
-	defaultPort = 3001
-	defaultDBPort = 5432
-	defaultPollIntervalMS = 60000
-	minPollIntervalMS = 1000
-)
-
-type Config struct {
-	Port              int
-	APIBasePath       string
-	DatabaseURL       string
-	DBHost            string
-	DBPort            int
-	DBUser            string
-	DBPassword        string
-	DBName            string
-	FirebaseProjectID string
-	EthRPCURL         string
-	PollIntervalMS    int
-	NodeEnv           string
-}
-
-// Load reads configuration from environment variables and returns a Config.
-func Load() (*Config, error) {
-	cfg := &Config{
-		Port:              getEnvInt("PORT", defaultPort),
-		APIBasePath:       getEnv("API_BASE_PATH", "/v1"),
-		DatabaseURL:       os.Getenv("DATABASE_URL"),
-		DBHost:            getEnv("DB_HOST", "localhost"),
-		DBPort:            getEnvInt("DB_PORT", defaultDBPort),
-		DBUser:            os.Getenv("DB_USER"),
-		DBPassword:        os.Getenv("DB_PASSWORD"),
-		DBName:            os.Getenv("DB_NAME"),
-		FirebaseProjectID: os.Getenv("FIREBASE_PROJECT_ID"),
-		EthRPCURL:         os.Getenv("ETH_RPC_URL"),
-		PollIntervalMS:    getEnvInt("POLL_INTERVAL_MS", defaultPollIntervalMS),
-		NodeEnv:           getEnv("NODE_ENV", "development"),
-	}
-
-	if cfg.PollIntervalMS < minPollIntervalMS {
-		return nil, fmt.Errorf("POLL_INTERVAL_MS must be >= 1000, got %d", cfg.PollIntervalMS) //nolint:err113
-	}
-
-	return cfg, nil
-}
-
-func (c *Config) DSN() string {
-	if c.DatabaseURL != "" {
-		// Append sslmode=disable if not already specified.
-		if !strings.Contains(c.DatabaseURL, "sslmode=") {
-			sep := "?"
-			if strings.Contains(c.DatabaseURL, "?") {
-				sep = "&"
-			}
-
-			return c.DatabaseURL + sep + "sslmode=disable"
-		}
-
-		return c.DatabaseURL
-	}
-
-	return fmt.Sprintf(
-		"host=%s port=%d user=%s password=%s dbname=%s sslmode=disable",
-		c.DBHost, c.DBPort, c.DBUser, c.DBPassword, c.DBName,
-	)
-}
-
-func getEnv(key, fallback string) string {
-	if v := os.Getenv(key); v != "" {
-		return v
-	}
-
-	return fallback
-}
-
-func getEnvInt(key string, fallback int) int {
-	if v := os.Getenv(key); v != "" {
-		if n, err := strconv.Atoi(v); err == nil {
-			return n
-		}
-	}
-
-	return fallback
-}

backend-go/internal/handlers/notification_config.go

@@ -1,128 +0,0 @@
-package handlers
-
-import (
-	"encoding/json"
-	"log"
-	"net/http"
-	"regexp"
-	"strings"
-
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
-	"github.com/kjannette/koin-ping/backend-go/internal/middleware"
-	"github.com/kjannette/koin-ping/backend-go/internal/models"
-)
-
-var emailRe = regexp.MustCompile(`^[^\s@]+@[^\s@]+\.[^\s@]+$`)
-
-type NotificationConfigHandler struct {
-	configs *models.NotificationConfigModel
-}
-
-func NewNotificationConfigHandler(configs *models.NotificationConfigModel) *NotificationConfigHandler {
-	return &NotificationConfigHandler{configs: configs}
-}
-
-func (h *NotificationConfigHandler) GetConfig(w http.ResponseWriter, r *http.Request) {
-	userID := middleware.GetUserID(r.Context())
-	log.Printf("User %s getting notification config", userID)
-
-	cfg, err := h.configs.GetConfig(r.Context(), userID)
-	if err != nil {
-		log.Printf("Error getting notification config: %v", err)
-		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to get notification config")
-		return
-	}
-
-	if cfg == nil {
-		writeJSON(w, http.StatusOK, domain.NotificationConfig{
-			UserID:              userID,
-			NotificationEnabled: true,
-		})
-		return
-	}
-
-	log.Println("Config found")
-	writeJSON(w, http.StatusOK, cfg)
-}
-
-func (h *NotificationConfigHandler) UpdateConfig(w http.ResponseWriter, r *http.Request) {
-	userID := middleware.GetUserID(r.Context())
-
-	var body struct {
-		DiscordWebhookURL   *string `json:"discord_webhook_url"`
-		TelegramChatID      *string `json:"telegram_chat_id"`
-		Email               *string `json:"email"`
-		NotificationEnabled *bool   `json:"notification_enabled"`
-	}
-	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
-		log.Printf("Failed to decode notification config request body: %v", err)
-		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "Invalid request body")
-		return
-	}
-
-	log.Printf("User %s updating notification config", userID)
-
-	if body.DiscordWebhookURL == nil && body.TelegramChatID == nil &&
-		body.Email == nil && body.NotificationEnabled == nil {
-		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR",
-			"At least one configuration field must be provided")
-		return
-	}
-
-	if body.DiscordWebhookURL != nil && *body.DiscordWebhookURL != "" &&
-		!strings.HasPrefix(*body.DiscordWebhookURL, "https://discord.com/api/webhooks/") {
-		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR",
-			"Invalid Discord webhook URL format")
-		return
-	}
-
-	if body.Email != nil && *body.Email != "" && !emailRe.MatchString(*body.Email) {
-		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR",
-			"Invalid email address format")
-		return
-	}
-
-	enabled := true
-	if body.NotificationEnabled != nil {
-		enabled = *body.NotificationEnabled
-	}
-
-	cfg := domain.NotificationConfig{
-		DiscordWebhookURL:   body.DiscordWebhookURL,
-		TelegramChatID:      body.TelegramChatID,
-		Email:               body.Email,
-		NotificationEnabled: enabled,
-	}
-
-	updated, err := h.configs.UpsertConfig(r.Context(), userID, cfg)
-	if err != nil {
-		log.Printf("Error updating notification config: %v", err)
-		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR",
-			"Failed to update notification configuration")
-		return
-	}
-
-	log.Println("Notification config updated")
-	writeJSON(w, http.StatusOK, updated)
-}
-
-func (h *NotificationConfigHandler) DeleteConfig(w http.ResponseWriter, r *http.Request) {
-	userID := middleware.GetUserID(r.Context())
-	log.Printf("User %s deleting notification config", userID)
-
-	deleted, err := h.configs.Remove(r.Context(), userID)
-	if err != nil {
-		log.Printf("Error deleting notification config: %v", err)
-		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR",
-			"Failed to delete notification configuration")
-		return
-	}
-
-	if !deleted {
-		writeError(w, http.StatusNotFound, "NOT_FOUND", "No notification configuration found")
-		return
-	}
-
-	log.Println("Notification config deleted")
-	w.WriteHeader(http.StatusNoContent)
-}

backend-go/internal/handlers/status.go

@@ -1,23 +0,0 @@
-package handlers
-
-import (
-	"net/http"
-	"time"
-)
-
-func HealthCheck(w http.ResponseWriter, r *http.Request) {
-	writeJSON(w, http.StatusOK, map[string]interface{}{
-		"status":    "ok",
-		"timestamp": time.Now().UTC().Format(time.RFC3339),
-		"service":   "koin-ping-backend",
-	})
-}
-
-func SystemStatus(w http.ResponseWriter, r *http.Request) {
-	writeJSON(w, http.StatusOK, map[string]interface{}{
-		"latestBlock": 0,
-		"lag":         0,
-		"status":      "healthy",
-		"timestamp":   time.Now().UTC().Format(time.RFC3339),
-	})
-}

backend-go/internal/middleware/auth.go

@@ -1,99 +0,0 @@
-// Package middleware provides HTTP middleware for authentication and context injection.
-package middleware
-
-import (
-	"context"
-	"encoding/json"
-	"log"
-	"net/http"
-	"strings"
-
-	fbauth "github.com/kjannette/koin-ping/backend-go/internal/firebase"
-)
-
-type contextKey string
-
-const (
-	UserIDKey    contextKey = "user_id"
-	UserEmailKey contextKey = "user_email"
-)
-
-type errorResponse struct {
-	Error   string `json:"error"`
-	Message string `json:"message"`
-}
-
-func writeJSON(w http.ResponseWriter, status int, v interface{}) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(status)
-	json.NewEncoder(w).Encode(v)
-}
-
-func Authenticate(next http.Handler) http.Handler {
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		authHeader := r.Header.Get("Authorization")
-		if authHeader == "" || !strings.HasPrefix(authHeader, "Bearer ") {
-			log.Println("No Authorization header or invalid format")
-			writeJSON(w, http.StatusUnauthorized, errorResponse{
-				Error:   "UNAUTHORIZED",
-				Message: "No authentication token provided",
-			})
-			return
-		}
-
-		token := strings.TrimPrefix(authHeader, "Bearer ")
-		if token == "" {
-			log.Println("Empty token")
-			writeJSON(w, http.StatusUnauthorized, errorResponse{
-				Error:   "UNAUTHORIZED",
-				Message: "Invalid token format",
-			})
-			return
-		}
-
-		log.Println("Verifying Firebase token...")
-		decoded, err := fbauth.Auth().VerifyIDToken(r.Context(), token)
-		if err != nil {
-			log.Printf("Token verification failed: %v", err)
-
-			errMsg := err.Error()
-			if strings.Contains(errMsg, "expired") {
-				writeJSON(w, http.StatusUnauthorized, errorResponse{
-					Error:   "TOKEN_EXPIRED",
-					Message: "Authentication token has expired",
-				})
-				return
-			}
-
-			writeJSON(w, http.StatusUnauthorized, errorResponse{
-				Error:   "UNAUTHORIZED",
-				Message: "Failed to verify authentication token",
-			})
-			return
-		}
-
-		userID := decoded.UID
-		email, _ := decoded.Claims["email"].(string)
-
-		log.Printf("Token verified! User ID: %s, Email: %s", userID, email)
-
-		ctx := context.WithValue(r.Context(), UserIDKey, userID)
-		ctx = context.WithValue(ctx, UserEmailKey, email)
-
-		next.ServeHTTP(w, r.WithContext(ctx))
-	})
-}
-
-func GetUserID(ctx context.Context) string {
-	if v, ok := ctx.Value(UserIDKey).(string); ok {
-		return v
-	}
-	return ""
-}
-
-func GetUserEmail(ctx context.Context) string {
-	if v, ok := ctx.Value(UserEmailKey).(string); ok {
-		return v
-	}
-	return ""
-}

backend-go/internal/models/alert_rule.go

@@ -1,115 +0,0 @@
-package models
-
-import (
-	"context"
-	"errors"
-
-	"github.com/jackc/pgx/v5"
-	"github.com/jackc/pgx/v5/pgxpool"
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
-)
-
-type AlertRuleModel struct {
-	pool *pgxpool.Pool
-}
-
-func NewAlertRuleModel(pool *pgxpool.Pool) *AlertRuleModel {
-	return &AlertRuleModel{pool: pool}
-}
-
-func (m *AlertRuleModel) Create(ctx context.Context, addressID int, alertType domain.AlertType, threshold *float64) (*domain.AlertRule, error) {
-	var r domain.AlertRule
-	err := m.pool.QueryRow(ctx,
-		`INSERT INTO alert_rules (address_id, type, threshold, enabled)
-		 VALUES ($1, $2, $3, TRUE)
-		 RETURNING id, address_id, type, threshold, enabled, created_at`,
-		addressID, alertType.String(), threshold,
-	).Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Enabled, &r.CreatedAt)
-	if err != nil {
-		return nil, err
-	}
-	return &r, nil
-}
-
-func (m *AlertRuleModel) ListByAddress(ctx context.Context, addressID int) ([]domain.AlertRule, error) {
-	rows, err := m.pool.Query(ctx,
-		`SELECT id, address_id, type, threshold, enabled, created_at
-		 FROM alert_rules
-		 WHERE address_id = $1
-		 ORDER BY created_at DESC`,
-		addressID,
-	)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-
-	var rules []domain.AlertRule
-	for rows.Next() {
-		var r domain.AlertRule
-		if err := rows.Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Enabled, &r.CreatedAt); err != nil {
-			return nil, err
-		}
-		rules = append(rules, r)
-	}
-	return rules, rows.Err()
-}
-
-func (m *AlertRuleModel) FindByID(ctx context.Context, id int, userID *string) (*domain.AlertRule, error) {
-	var r domain.AlertRule
-	var err error
-
-	if userID != nil {
-		err = m.pool.QueryRow(ctx,
-			`SELECT ar.id, ar.address_id, ar.type, ar.threshold, ar.enabled, ar.created_at
-			 FROM alert_rules ar
-			 JOIN addresses a ON a.id = ar.address_id
-			 WHERE ar.id = $1 AND a.user_id = $2`,
-			id, *userID,
-		).Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Enabled, &r.CreatedAt)
-	} else {
-		err = m.pool.QueryRow(ctx,
-			`SELECT id, address_id, type, threshold, enabled, created_at
-			 FROM alert_rules
-			 WHERE id = $1`,
-			id,
-		).Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Enabled, &r.CreatedAt)
-	}
-
-	if err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return nil, nil
-		}
-		return nil, err
-	}
-	return &r, nil
-}
-
-func (m *AlertRuleModel) UpdateEnabled(ctx context.Context, id int, enabled bool) (*domain.AlertRule, error) {
-	var r domain.AlertRule
-	err := m.pool.QueryRow(ctx,
-		`UPDATE alert_rules
-		 SET enabled = $2
-		 WHERE id = $1
-		 RETURNING id, address_id, type, threshold, enabled, created_at`,
-		id, enabled,
-	).Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Enabled, &r.CreatedAt)
-	if err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return nil, nil
-		}
-		return nil, err
-	}
-	return &r, nil
-}
-
-func (m *AlertRuleModel) Remove(ctx context.Context, id int) (bool, error) {
-	tag, err := m.pool.Exec(ctx,
-		`DELETE FROM alert_rules WHERE id = $1`,
-		id,
-	)
-	if err != nil {
-		return false, err
-	}
-	return tag.RowsAffected() > 0, nil
-}

backend-go/internal/protocols/ethereum/jsonrpc.go

@@ -1,211 +0,0 @@
-package ethereum
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"fmt"
-	"math/big"
-	"net/http"
-	"strings"
-	"time"
-
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
-)
-
-const rpcTimeoutMS = 30000
-
-type JsonRpcEthereum struct {
-	rpcURL string
-	client *http.Client
-}
-
-func NewJsonRpcEthereum(rpcURL string) (*JsonRpcEthereum, error) {
-	if rpcURL == "" {
-		return nil, fmt.Errorf("JsonRpcEthereum requires a valid RPC URL")
-	}
-	return &JsonRpcEthereum{
-		rpcURL: rpcURL,
-		client: &http.Client{
-			Timeout: time.Duration(rpcTimeoutMS) * time.Millisecond,
-		},
-	}, nil
-}
-
-type rpcRequest struct {
-	JSONRPC string        `json:"jsonrpc"`
-	ID      int64         `json:"id"`
-	Method  string        `json:"method"`
-	Params  []interface{} `json:"params"`
-}
-
-type rpcResponse struct {
-	JSONRPC string          `json:"jsonrpc"`
-	ID      int64           `json:"id"`
-	Result  json.RawMessage `json:"result"`
-	Error   *rpcError       `json:"error"`
-}
-
-type rpcError struct {
-	Code    int    `json:"code"`
-	Message string `json:"message"`
-}
-
-func (j *JsonRpcEthereum) callRPC(ctx context.Context, method string, params ...interface{}) (json.RawMessage, error) {
-	if params == nil {
-		params = []interface{}{}
-	}
-
-	body, err := json.Marshal(rpcRequest{
-		JSONRPC: "2.0",
-		ID:      time.Now().UnixMilli(),
-		Method:  method,
-		Params:  params,
-	})
-	if err != nil {
-		return nil, fmt.Errorf("marshal RPC request: %w", err)
-	}
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, j.rpcURL, bytes.NewReader(body))
-	if err != nil {
-		return nil, fmt.Errorf("create RPC request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-
-	resp, err := j.client.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("RPC call failed [%s]: %w", method, err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("HTTP %d: %s for %s", resp.StatusCode, resp.Status, method)
-	}
-
-	var rpcResp rpcResponse
-	if err := json.NewDecoder(resp.Body).Decode(&rpcResp); err != nil {
-		return nil, fmt.Errorf("decode RPC response: %w", err)
-	}
-
-	if rpcResp.Error != nil {
-		return nil, fmt.Errorf("RPC Error [%s]: %s (code: %d)", method, rpcResp.Error.Message, rpcResp.Error.Code)
-	}
-
-	return rpcResp.Result, nil
-}
-
-func (j *JsonRpcEthereum) GetLatestBlockNumber(ctx context.Context) (int, error) {
-	result, err := j.callRPC(ctx, "eth_blockNumber")
-	if err != nil {
-		return 0, err
-	}
-
-	var hexBlock string
-	if err := json.Unmarshal(result, &hexBlock); err != nil {
-		return 0, fmt.Errorf("unmarshal block number: %w", err)
-	}
-
-	return hexToInt(hexBlock)
-}
-
-type rpcBlock struct {
-	Timestamp    string  `json:"timestamp"`
-	Transactions []rpcTx `json:"transactions"`
-}
-
-type rpcTx struct {
-	Hash        string  `json:"hash"`
-	From        string  `json:"from"`
-	To          *string `json:"to"`
-	Value       string  `json:"value"`
-	BlockNumber string  `json:"blockNumber"`
-}
-
-func (j *JsonRpcEthereum) GetBlockTransactions(ctx context.Context, blockNumber int) ([]domain.NormalizedTx, error) {
-	hexBlock := fmt.Sprintf("0x%x", blockNumber)
-
-	result, err := j.callRPC(ctx, "eth_getBlockByNumber", hexBlock, true)
-	if err != nil {
-		return nil, err
-	}
-
-	if string(result) == "null" {
-		return nil, nil
-	}
-
-	var block rpcBlock
-	if err := json.Unmarshal(result, &block); err != nil {
-		return nil, fmt.Errorf("unmarshal block: %w", err)
-	}
-
-	blockTimestamp, err := hexToInt64(block.Timestamp)
-	if err != nil {
-		return nil, fmt.Errorf("parse block timestamp: %w", err)
-	}
-
-	txs := make([]domain.NormalizedTx, 0, len(block.Transactions))
-	for _, tx := range block.Transactions {
-		bn, _ := hexToInt(tx.BlockNumber)
-
-		var toLower *string
-		if tx.To != nil {
-			s := strings.ToLower(*tx.To)
-			toLower = &s
-		}
-
-		txs = append(txs, domain.NormalizedTx{
-			Hash:           tx.Hash,
-			From:           strings.ToLower(tx.From),
-			To:             toLower,
-			Value:          hexToDecimalString(tx.Value),
-			BlockNumber:    bn,
-			BlockTimestamp: blockTimestamp,
-		})
-	}
-
-	return txs, nil
-}
-
-func (j *JsonRpcEthereum) GetBalance(ctx context.Context, address string) (string, error) {
-	result, err := j.callRPC(ctx, "eth_getBalance", address, "latest")
-	if err != nil {
-		return "", err
-	}
-
-	var hexBalance string
-	if err := json.Unmarshal(result, &hexBalance); err != nil {
-		return "", fmt.Errorf("unmarshal balance: %w", err)
-	}
-
-	return hexToDecimalString(hexBalance), nil
-}
-
-func hexToInt(hex string) (int, error) {
-	hex = strings.TrimPrefix(hex, "0x")
-	n, ok := new(big.Int).SetString(hex, 16)
-	if !ok {
-		return 0, fmt.Errorf("invalid hex: %s", hex)
-	}
-	return int(n.Int64()), nil
-}
-
-func hexToInt64(hex string) (int64, error) {
-	hex = strings.TrimPrefix(hex, "0x")
-	n, ok := new(big.Int).SetString(hex, 16)
-	if !ok {
-		return 0, fmt.Errorf("invalid hex: %s", hex)
-	}
-	return n.Int64(), nil
-}
-
-func hexToDecimalString(hex string) string {
-	if hex == "" || hex == "0x" || hex == "0x0" {
-		return "0"
-	}
-	clean := strings.TrimPrefix(hex, "0x")
-	n, ok := new(big.Int).SetString(clean, 16)
-	if !ok {
-		return "0"
-	}
-	return n.String()
-}

backend-go/internal/services/evaluator.go

@@ -1,236 +0,0 @@
-package services
-
-import (
-	"context"
-	"fmt"
-	"log"
-
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
-	"github.com/kjannette/koin-ping/backend-go/internal/models"
-	"github.com/kjannette/koin-ping/backend-go/internal/notifications"
-	"github.com/kjannette/koin-ping/backend-go/internal/protocols/ethereum"
-	"github.com/kjannette/koin-ping/backend-go/internal/wei"
-)
-
-type EvaluatorService struct {
-	eth          ethereum.EthereumObserver
-	alertRules   *models.AlertRuleModel
-	alertEvents  *models.AlertEventModel
-	addresses    *models.AddressModel
-	notifConfigs *models.NotificationConfigModel
-}
-
-func NewEvaluatorService(
-	eth ethereum.EthereumObserver,
-	alertRules *models.AlertRuleModel,
-	alertEvents *models.AlertEventModel,
-	addresses *models.AddressModel,
-	notifConfigs *models.NotificationConfigModel,
-) *EvaluatorService {
-	return &EvaluatorService{
-		eth:          eth,
-		alertRules:   alertRules,
-		alertEvents:  alertEvents,
-		addresses:    addresses,
-		notifConfigs: notifConfigs,
-	}
-}
-
-func (s *EvaluatorService) Evaluate(ctx context.Context, observations []domain.ObservedTx) (int, error) {
-	alertsFired := 0
-
-	for _, obs := range observations {
-		fired, err := s.evaluateObservation(ctx, obs)
-		if err != nil {
-			log.Printf("Error evaluating observation for address ID %d: %v", obs.AddressID, err)
-			continue
-		}
-		alertsFired += fired
-	}
-
-	return alertsFired, nil
-}
-
-func (s *EvaluatorService) evaluateObservation(ctx context.Context, obs domain.ObservedTx) (int, error) {
-	rules, err := s.alertRules.ListByAddress(ctx, obs.AddressID)
-	if err != nil {
-		return 0, err
-	}
-
-	alertsFired := 0
-	for _, rule := range rules {
-		if !rule.Enabled {
-			continue
-		}
-
-		matches, err := s.ruleMatches(ctx, rule, obs)
-		if err != nil {
-			log.Printf("Error matching rule %d: %v", rule.ID, err)
-			continue
-		}
-
-		if matches {
-			if err := s.fireAlert(ctx, rule, obs); err != nil {
-				log.Printf("Error firing alert for rule %d: %v", rule.ID, err)
-				continue
-			}
-			alertsFired++
-		}
-	}
-
-	return alertsFired, nil
-}
-
-func (s *EvaluatorService) ruleMatches(ctx context.Context, rule domain.AlertRule, obs domain.ObservedTx) (bool, error) {
-	switch rule.Type {
-	case domain.AlertIncomingTx:
-		return obs.Direction == domain.DirectionIncoming, nil
-	case domain.AlertOutgoingTx:
-		return obs.Direction == domain.DirectionOutgoing, nil
-	case domain.AlertLargeTransfer:
-		return s.matchesLargeTransfer(rule, obs)
-	case domain.AlertBalanceBelow:
-		return s.matchesBalanceBelow(ctx, rule, obs)
-	default:
-		log.Printf("Unknown rule type: %s", rule.Type)
-		return false, nil
-	}
-}
-
-func (s *EvaluatorService) matchesLargeTransfer(rule domain.AlertRule, obs domain.ObservedTx) (bool, error) {
-	if rule.Threshold == nil {
-		return false, nil
-	}
-
-	thresholdWei, err := wei.FromEth(*rule.Threshold)
-	if err != nil {
-		return false, err
-	}
-
-	return wei.GreaterThanOrEqual(obs.Value, thresholdWei)
-}
-
-// matchesBalanceBelow only triggers after outgoing transactions, since incoming
-// transactions increase balance and can't cause it to drop below threshold.
-func (s *EvaluatorService) matchesBalanceBelow(ctx context.Context, rule domain.AlertRule, obs domain.ObservedTx) (bool, error) {
-	if rule.Threshold == nil {
-		return false, nil
-	}
-
-	if obs.Direction != domain.DirectionOutgoing {
-		return false, nil
-	}
-
-	addr, err := s.addresses.FindByID(ctx, obs.AddressID, nil)
-	if err != nil {
-		return false, err
-	}
-	if addr == nil {
-		log.Printf("Address ID %d not found", obs.AddressID)
-		return false, nil
-	}
-
-	balanceWei, err := s.eth.GetBalance(ctx, addr.Address)
-	if err != nil {
-		return false, err
-	}
-
-	thresholdWei, err := wei.FromEth(*rule.Threshold)
-	if err != nil {
-		return false, err
-	}
-
-	return wei.LessThan(balanceWei, thresholdWei)
-}
-
-func (s *EvaluatorService) fireAlert(ctx context.Context, rule domain.AlertRule, obs domain.ObservedTx) error {
-	addr, err := s.addresses.FindByID(ctx, obs.AddressID, nil)
-	if err != nil {
-		return err
-	}
-
-	addressLabel := "Unknown"
-	if addr != nil {
-		if addr.Label != nil {
-			addressLabel = *addr.Label
-		} else {
-			addressLabel = addr.Address
-		}
-	}
-
-	message := s.buildMessage(rule, obs)
-	txHash := &obs.Hash
-
-	_, err = s.alertEvents.Create(ctx, rule.ID, message, &addressLabel, txHash)
-	if err != nil {
-		return err
-	}
-
-	log.Printf("[ALERT FIRED] Rule %d (%s) - %s - TX: %s", rule.ID, rule.Type, message, obs.Hash)
-
-	// Send Discord notification (non-fatal on failure)
-	if addr != nil {
-		go func() {
-			s.sendNotification(
-				ctx, addr.UserID, message, obs, addressLabel, rule, addr.Address,
-			)
-		}()
-	}
-
-	return nil
-}
-
-func (s *EvaluatorService) sendNotification(ctx context.Context, userID, message string, obs domain.ObservedTx, addressLabel string, rule domain.AlertRule, address string) {
-	notifConfig, err := s.notifConfigs.GetConfig(ctx, userID)
-	if err != nil {
-		log.Printf("Failed to get notification config: %v", err)
-		return
-	}
-
-	if notifConfig == nil || !notifConfig.NotificationEnabled || notifConfig.DiscordWebhookURL == nil {
-		return
-	}
-
-	sent, err := notifications.SendDiscordNotification(
-		*notifConfig.DiscordWebhookURL,
-		message,
-		notifications.AlertMetadata{
-			TxHash:       obs.Hash,
-			AddressLabel: addressLabel,
-			AlertType:    string(rule.Type),
-			Address:      address,
-		},
-	)
-
-	if err != nil || !sent {
-		log.Printf("Discord notification failed for user %s: %v", userID, err)
-	} else {
-		log.Printf("Discord notification sent to user %s", userID)
-	}
-}
-
-func (s *EvaluatorService) buildMessage(rule domain.AlertRule, obs domain.ObservedTx) string {
-	switch rule.Type {
-	case domain.AlertIncomingTx:
-		ethStr, _ := wei.FormatAsEth(obs.Value, 4)
-		return fmt.Sprintf("Incoming transaction: %s received", ethStr)
-	case domain.AlertOutgoingTx:
-		ethStr, _ := wei.FormatAsEth(obs.Value, 4)
-		return fmt.Sprintf("Outgoing transaction: %s sent", ethStr)
-	case domain.AlertLargeTransfer:
-		ethStr, _ := wei.FormatAsEth(obs.Value, 4)
-		threshold := float64(0)
-		if rule.Threshold != nil {
-			threshold = *rule.Threshold
-		}
-		return fmt.Sprintf("Large transfer detected: %s (threshold: %g ETH)", ethStr, threshold)
-	case domain.AlertBalanceBelow:
-		threshold := float64(0)
-		if rule.Threshold != nil {
-			threshold = *rule.Threshold
-		}
-		return fmt.Sprintf("Balance dropped below threshold of %g ETH", threshold)
-	default:
-		return "Alert triggered"
-	}
-}

backend/Makefile

@@ -37,7 +37,7 @@ tidy:
 
 # Database setup
 db-setup:
-	psql -d koin_ping_dev -f infra/schema.sql
+	psql -d koin_ping -f infra/schema.sql
 
 vet:
 	go vet ./...

backend/README.md

@@ -0,0 +1,33 @@
+Backend startup quickstart:
+
+----------------------------->  BEST
+## 1. brew services start postgresql@15
+
+          OR 
+
+      /opt/homebrew/opt/postgresql@15/bin/pg_ctl -D /opt/homebrew/var/postgresql@15 start
+
+## 2.   ALLIN ONE: 
+        Make dev-all — Runs both the API and poller concurrently.
+----------------------------->  BEST
+
+          - OR - 
+          
+           
+## 3.  Option 1: Single command (both API + poller)
+       cd /Users/kjannette/workspace/koin_ping_0.2.0/backendmake dev-all
+
+## 4.   Option 2: Two separate terminals
+        Terminal 1 (API server):
+        cd /Users/kjannette/workspace/koin_ping_0.2.0/backend go run ./cmd/api
+        
+        make run — Builds and runs the API server.
+        make dev — Runs the API server with auto-reload via air (falls back to go run if air isn't installed).
+
+## 5.   Terminal 2 (Poller):
+        cd /Users/kjannette/workspace/koin_ping_0.2.0/backend 
+        go run ./cmd/poller
+
+        make poller — Builds and runs the poller.
+        make poller-dev — Runs the poller with auto-reload.
+

backend/cmd/api/main.go

@@ -0,0 +1,181 @@
+// Package main is the entry point for the API server.
+package main
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/joho/godotenv"
+	"github.com/kjannette/koin-ping/backend/internal/config"
+	"github.com/kjannette/koin-ping/backend/internal/database"
+	"github.com/kjannette/koin-ping/backend/internal/firebase"
+	"github.com/kjannette/koin-ping/backend/internal/handlers"
+	"github.com/kjannette/koin-ping/backend/internal/middleware"
+	"github.com/kjannette/koin-ping/backend/internal/models"
+	"github.com/kjannette/koin-ping/backend/internal/services"
+)
+
+const (
+	// max duration to read a request.
+	serverReadTimeoutSeconds = 5
+	// maxiduration to write a response.
+	serverWriteTimeoutSeconds = 10
+)
+
+//nolint:funlen
+func main() {
+	_ = godotenv.Load() // .env is optional; env vars can also be set externally
+
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("Failed to load config: %v", err)
+	}
+
+	pool, err := database.Connect(cfg.DSN())
+	if err != nil {
+		log.Fatalf("Failed to connect to database: %v", err)
+	}
+
+	if err := firebase.Init(cfg.FirebaseProjectID); err != nil {
+		log.Fatalf("Failed to initialize Firebase: %v", err)
+	}
+
+	defer database.Close()
+
+	userModel := models.NewUserModel(pool)
+	addressModel := models.NewAddressModel(pool)
+	alertRuleModel := models.NewAlertRuleModel(pool)
+	alertEventModel := models.NewAlertEventModel(pool)
+	checkpointModel := models.NewCheckpointModel(pool)
+	notifConfigModel := models.NewNotificationConfigModel(pool)
+
+	emailDigestSvc := services.NewEmailDigestService(
+		cfg.ResendAPIKey, cfg.EmailFrom, alertEventModel, notifConfigModel,
+	)
+
+	addressHandler := handlers.NewAddressHandler(addressModel, userModel)
+	alertRuleHandler := handlers.NewAlertRuleHandler(alertRuleModel, addressModel, userModel)
+	alertEventHandler := handlers.NewAlertEventHandler(alertEventModel)
+	notifConfigHandler := handlers.NewNotificationConfigHandler(notifConfigModel, userModel, cfg)
+	emailDigestHandler := handlers.NewEmailDigestHandler(emailDigestSvc, notifConfigModel)
+	statusHandler := handlers.NewStatusHandler(checkpointModel)
+	stripeHandler := handlers.NewStripeHandler(userModel, alertRuleModel, cfg)
+	accountHandler := handlers.NewAccountHandler(userModel, addressModel, cfg)
+	supportHandler := handlers.NewSupportHandler(cfg)
+
+	authenticate := middleware.Authenticate(userModel)
+	requireSub := middleware.RequireSubscription(userModel)
+
+	// authAndSub chains authentication + subscription check for protected routes.
+	authAndSub := func(h http.Handler) http.Handler {
+		return authenticate(requireSub(h))
+	}
+
+	mux := http.NewServeMux()
+	b := cfg.APIBasePath // e.g. "/v1"
+
+	// Public routes
+	mux.HandleFunc("GET "+b+"/health", handlers.HealthCheck)
+	mux.HandleFunc("GET "+b+"/status", statusHandler.GetStatus)
+
+	// Stripe webhook (public — called by Stripe, not authenticated)
+	mux.HandleFunc("POST "+b+"/stripe/webhook", stripeHandler.HandleWebhook)
+
+	// Onboarding checkout (public — account doesn't exist yet)
+	mux.HandleFunc("POST "+b+"/stripe/create-onboarding-checkout", stripeHandler.CreateOnboardingCheckout)
+
+	// Stripe routes (auth required, NO subscription required)
+	mux.Handle("POST "+b+"/stripe/create-checkout-session",
+		authenticate(http.HandlerFunc(stripeHandler.CreateCheckoutSession)))
+	mux.Handle("GET "+b+"/stripe/subscription-status",
+		authenticate(http.HandlerFunc(stripeHandler.GetSubscriptionStatus)))
+	mux.Handle("POST "+b+"/stripe/verify-checkout",
+		authenticate(http.HandlerFunc(stripeHandler.VerifyCheckoutSession)))
+	mux.Handle("POST "+b+"/stripe/create-portal-session",
+		authenticate(http.HandlerFunc(stripeHandler.CreatePortalSession)))
+	mux.Handle("POST "+b+"/stripe/activate-free",
+		authenticate(http.HandlerFunc(stripeHandler.ActivateFreeTier)))
+
+	// Account route (auth required, NO subscription required)
+	mux.Handle("GET "+b+"/user/account",
+		authenticate(http.HandlerFunc(accountHandler.GetAccount)))
+
+	// Support (auth required; avoids anonymous spam)
+	mux.Handle("POST "+b+"/support",
+		authenticate(http.HandlerFunc(supportHandler.Submit)))
+
+	// Authenticated + subscribed routes — addresses
+	mux.Handle("POST "+b+"/addresses",
+		authAndSub(http.HandlerFunc(addressHandler.Create)))
+	mux.Handle("GET "+b+"/addresses",
+		authAndSub(http.HandlerFunc(addressHandler.List)))
+	mux.Handle("DELETE "+b+"/addresses/{addressId}",
+		authAndSub(http.HandlerFunc(addressHandler.Remove)))
+	mux.Handle("PATCH "+b+"/addresses/{addressId}",
+		authAndSub(http.HandlerFunc(addressHandler.UpdateLabel)))
+
+	// Authenticated + subscribed routes — alert rules
+	mux.Handle("POST "+b+"/addresses/{addressId}/alerts",
+		authAndSub(http.HandlerFunc(alertRuleHandler.Create)))
+	mux.Handle("GET "+b+"/addresses/{addressId}/alerts",
+		authAndSub(http.HandlerFunc(alertRuleHandler.ListByAddress)))
+	mux.Handle("PATCH "+b+"/alerts/{alertId}",
+		authAndSub(http.HandlerFunc(alertRuleHandler.UpdateStatus)))
+	mux.Handle("DELETE "+b+"/alerts/{alertId}",
+		authAndSub(http.HandlerFunc(alertRuleHandler.Remove)))
+
+	// Authenticated + subscribed routes — alert events
+	mux.Handle("GET "+b+"/alert-events",
+		authAndSub(http.HandlerFunc(alertEventHandler.List)))
+
+	// Authenticated + subscribed routes — notification config
+	mux.Handle("GET "+b+"/notification-config",
+		authAndSub(http.HandlerFunc(notifConfigHandler.GetConfig)))
+	mux.Handle("PUT "+b+"/notification-config",
+		authAndSub(http.HandlerFunc(notifConfigHandler.UpdateConfig)))
+	mux.Handle("DELETE "+b+"/notification-config",
+		authAndSub(http.HandlerFunc(notifConfigHandler.DeleteConfig)))
+	mux.Handle("POST "+b+"/notification-config/test",
+		authAndSub(http.HandlerFunc(notifConfigHandler.TestChannels)))
+
+	// Authenticated + subscribed routes — email digest
+	mux.Handle("POST "+b+"/email/setup",
+		authAndSub(http.HandlerFunc(emailDigestHandler.SetupEmail)))
+	mux.Handle("POST "+b+"/email/digest",
+		authAndSub(http.HandlerFunc(emailDigestHandler.SendDigest)))
+
+	handler := corsMiddleware(mux)
+
+	addr := fmt.Sprintf(":%d", cfg.Port)
+	log.Printf("Server running on port %d", cfg.Port)
+	log.Printf("API base path: %s", cfg.APIBasePath)
+	log.Printf("Environment: %s", cfg.NodeEnv)
+
+	server := &http.Server{
+		Addr:         addr,
+		Handler:      handler,
+		ReadTimeout:  serverReadTimeoutSeconds * time.Second,
+		WriteTimeout: serverWriteTimeoutSeconds * time.Second,
+	}
+	if err := server.ListenAndServe(); err != nil {
+		log.Fatalf("Server failed: %v", err)
+	}
+}
+
+func corsMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
+
+		if r.Method == http.MethodOptions {
+			w.WriteHeader(http.StatusNoContent)
+
+			return
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}

backend/cmd/poller/main.go

@@ -12,11 +12,11 @@ import (
 	"time"
 
 	"github.com/joho/godotenv"
-	"github.com/kjannette/koin-ping/backend-go/internal/config"
-	"github.com/kjannette/koin-ping/backend-go/internal/database"
-	"github.com/kjannette/koin-ping/backend-go/internal/models"
-	"github.com/kjannette/koin-ping/backend-go/internal/protocols/ethereum"
-	"github.com/kjannette/koin-ping/backend-go/internal/services"
+	"github.com/kjannette/koin-ping/backend/internal/config"
+	"github.com/kjannette/koin-ping/backend/internal/database"
+	"github.com/kjannette/koin-ping/backend/internal/models"
+	"github.com/kjannette/koin-ping/backend/internal/protocols/ethereum"
+	"github.com/kjannette/koin-ping/backend/internal/services"
 )
 
 const (
@@ -51,6 +51,7 @@ func main() {
 
 	defer database.Close()
 
+	userModel := models.NewUserModel(pool)
 	addressModel := models.NewAddressModel(pool)
 	alertRuleModel := models.NewAlertRuleModel(pool)
 	alertEventModel := models.NewAlertEventModel(pool)
@@ -58,7 +59,10 @@ func main() {
 	notifConfigModel := models.NewNotificationConfigModel(pool)
 
 	observer := services.NewObserverService(eth, addressModel, checkpointModel)
-	evaluator := services.NewEvaluatorService(eth, alertRuleModel, alertEventModel, addressModel, notifConfigModel)
+	evaluator := services.NewEvaluatorService(
+		eth, alertRuleModel, alertEventModel, addressModel, userModel, notifConfigModel,
+	)
+	digestSvc := services.NewEmailDigestService(cfg.ResendAPIKey, cfg.EmailFrom, alertEventModel, notifConfigModel)
 
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
@@ -75,12 +79,14 @@ func main() {
 	}()
 
 	interval := time.Duration(cfg.PollIntervalMS) * time.Millisecond
+	digestInterval := time.Duration(cfg.DigestIntervalHours) * time.Hour
 
 	log.Println(strings.Repeat("=", separatorWidth))
 	log.Println("Koin Ping Observer Poller Starting")
 	log.Println(strings.Repeat("=", separatorWidth))
 	log.Printf("RPC URL: %s", cfg.EthRPCURL)
 	log.Printf("Poll Interval: %dms (%ds)", cfg.PollIntervalMS, cfg.PollIntervalMS/msPerSecond)
+	log.Printf("Digest Interval: %dh", cfg.DigestIntervalHours)
 	log.Println(strings.Repeat("=", separatorWidth))
 
 	runCycle(ctx, observer, evaluator)
@@ -88,6 +94,9 @@ func main() {
 	ticker := time.NewTicker(interval)
 	defer ticker.Stop()
 
+	digestTicker := time.NewTicker(digestInterval)
+	defer digestTicker.Stop()
+
 	for {
 		select {
 		case <-ctx.Done():
@@ -96,6 +105,13 @@ func main() {
 			return
 		case <-ticker.C:
 			runCycle(ctx, observer, evaluator)
+		case <-digestTicker.C:
+			sent, digestErr := digestSvc.SendDigestsForAllUsers(ctx)
+			if digestErr != nil {
+				log.Printf("Email digest failed: %v", digestErr)
+			} else {
+				log.Printf("Sent %d email digests", sent)
+			}
 		}
 	}
 }
@@ -122,6 +138,8 @@ func runCycle(
 		return
 	}
 
+	evaluator.WaitForNotifications()
+
 	duration := time.Since(startTime)
 	log.Printf("[%s] Cycle complete: %d observations, %d alerts fired in %s",
 		time.Now().UTC().Format(time.RFC3339),

backend/cmd/subscription-sweep/main.go

@@ -0,0 +1,68 @@
+// Package main runs a daily (cron-invoked) job: for paid tiers without an
+// active or trialling Stripe subscription, disable Firebase login and turn
+// off all alert rules until billing is restored via Stripe webhook / checkout.
+package main
+
+import (
+	"context"
+	"log"
+
+	"github.com/joho/godotenv"
+
+	"github.com/kjannette/koin-ping/backend/internal/config"
+	"github.com/kjannette/koin-ping/backend/internal/database"
+	"github.com/kjannette/koin-ping/backend/internal/firebase"
+	"github.com/kjannette/koin-ping/backend/internal/models"
+)
+
+func main() {
+	_ = godotenv.Load()
+
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("Failed to load config: %v", err)
+	}
+
+	if err := firebase.Init(cfg.FirebaseProjectID); err != nil {
+		log.Fatalf("Failed to initialize Firebase: %v", err)
+	}
+
+	pool, connErr := database.Connect(cfg.DSN())
+	if connErr != nil {
+		log.Fatalf("Failed to connect to database: %v", connErr)
+	}
+
+	defer database.Close()
+
+	ctx := context.Background()
+	userModel := models.NewUserModel(pool)
+	alertModel := models.NewAlertRuleModel(pool)
+
+	users, listErr := userModel.ListPaidUsersWithoutActiveSubscription(ctx)
+	if listErr != nil {
+		log.Fatalf("Failed to list lapsed subscriptions: %v", listErr)
+	}
+
+	if len(users) == 0 {
+		log.Println("Subscription sweep: no lapsed paid users")
+		return
+	}
+
+	for _, u := range users {
+		if disableErr := firebase.SetUserDisabled(ctx, u.FirebaseUID, true); disableErr != nil {
+			log.Printf("Subscription sweep: Firebase disable failed user %s: %v", u.ID, disableErr)
+			continue
+		}
+
+		n, rulesErr := alertModel.DisableAllForUser(ctx, u.ID)
+		if rulesErr != nil {
+			log.Printf("Subscription sweep: disabling alerts failed for user %s: %v", u.ID, rulesErr)
+			continue
+		}
+
+		log.Printf(
+			"Subscription sweep: suspended user %s (%s tier, status=%s), disabled %d alert rules",
+			u.ID, u.SubscriptionTier, u.SubscriptionStatus, n,
+		)
+	}
+}

backend/go.mod

@@ -1,10 +1,13 @@
-module github.com/kjannette/koin-ping/backend-go
+module github.com/kjannette/koin-ping/backend
 
 go 1.25.0
 
 require (
 	firebase.google.com/go/v4 v4.19.0
-	github.com/jackc/pgx/v5 v5.8.0
+	github.com/jackc/pgx/v5 v5.9.2
+	github.com/joho/godotenv v1.5.1
+	github.com/stripe/stripe-go/v82 v82.5.1
+	golang.org/x/sync v0.19.0
 	google.golang.org/api v0.269.0
 )
 
@@ -40,23 +43,21 @@ require (
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
-	github.com/joho/godotenv v1.5.1 // indirect
 	github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 // indirect
 	github.com/spiffe/go-spiffe/v2 v2.6.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
 	go.opentelemetry.io/contrib/detectors/gcp v1.39.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.61.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0 // indirect
-	go.opentelemetry.io/otel v1.39.0 // indirect
-	go.opentelemetry.io/otel/metric v1.39.0 // indirect
-	go.opentelemetry.io/otel/sdk v1.39.0 // indirect
-	go.opentelemetry.io/otel/sdk/metric v1.39.0 // indirect
-	go.opentelemetry.io/otel/trace v1.39.0 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.43.0 // indirect
+	go.opentelemetry.io/otel/sdk/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
 	golang.org/x/crypto v0.48.0 // indirect
 	golang.org/x/net v0.50.0 // indirect
 	golang.org/x/oauth2 v0.35.0 // indirect
-	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/text v0.34.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	google.golang.org/appengine/v2 v2.0.6 // indirect
@@ -66,3 +67,11 @@ require (
 	google.golang.org/grpc v1.79.1 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 )
+
+replace google.golang.org/grpc v1.79.1 => google.golang.org/grpc v1.79.3
+
+replace go.opentelemetry.io/otel v1.39.0 => go.opentelemetry.io/otel v1.41.0
+
+replace go.opentelemetry.io/otel/sdk v1.39.0 => go.opentelemetry.io/otel/sdk v1.43.0
+
+replace github.com/go-jose/go-jose/v4 v4.1.3 => github.com/go-jose/go-jose/v4 v4.1.4

backend/go.sum

@@ -51,8 +51,8 @@ github.com/envoyproxy/protoc-gen-validate v1.3.0 h1:TvGH1wof4H33rezVKWSpqKz5NXWg
 github.com/envoyproxy/protoc-gen-validate v1.3.0/go.mod h1:HvYl7zwPa5mffgyeTUHA9zHIH36nmrm7oCbo4YKoSWA=
 github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
 github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
-github.com/go-jose/go-jose/v4 v4.1.3 h1:CVLmWDhDVRa6Mi/IgCgaopNosCaHz7zrMeF9MlZRkrs=
-github.com/go-jose/go-jose/v4 v4.1.3/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
+github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
+github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
@@ -81,8 +81,8 @@ github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsI
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
-github.com/jackc/pgx/v5 v5.8.0 h1:TYPDoleBBme0xGSAX3/+NujXXtpZn9HBONkQC7IEZSo=
-github.com/jackc/pgx/v5 v5.8.0/go.mod h1:QVeDInX2m9VyzvNeiCJVjCkNFqzsNb43204HshNSZKw=
+github.com/jackc/pgx/v5 v5.9.2 h1:3ZhOzMWnR4yJ+RW1XImIPsD1aNSz4T4fyP7zlQb56hw=
+github.com/jackc/pgx/v5 v5.9.2/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
@@ -99,6 +99,8 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/stripe/stripe-go/v82 v82.5.1 h1:05q6ZDKoe8PLMpQV072obF74HCgP4XJeJYoNuRSX2+8=
+github.com/stripe/stripe-go/v82 v82.5.1/go.mod h1:majCQX6AfObAvJiHraPi/5udwHi4ojRvJnnxckvHrX8=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
@@ -108,18 +110,18 @@ go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.6
 go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.61.0/go.mod h1:snMWehoOh2wsEwnvvwtDyFCxVeDAODenXHtn5vzrKjo=
 go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0 h1:F7Jx+6hwnZ41NSFTO5q4LYDtJRXBf2PD0rNBkeB/lus=
 go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0/go.mod h1:UHB22Z8QsdRDrnAtX4PntOl36ajSxcdUMt1sF7Y6E7Q=
-go.opentelemetry.io/otel v1.39.0 h1:8yPrr/S0ND9QEfTfdP9V+SiwT4E0G7Y5MO7p85nis48=
-go.opentelemetry.io/otel v1.39.0/go.mod h1:kLlFTywNWrFyEdH0oj2xK0bFYZtHRYUdv1NklR/tgc8=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
 go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.36.0 h1:rixTyDGXFxRy1xzhKrotaHy3/KXdPhlWARrCgK+eqUY=
 go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.36.0/go.mod h1:dowW6UsM9MKbJq5JTz2AMVp3/5iW5I/TStsk8S+CfHw=
-go.opentelemetry.io/otel/metric v1.39.0 h1:d1UzonvEZriVfpNKEVmHXbdf909uGTOQjA0HF0Ls5Q0=
-go.opentelemetry.io/otel/metric v1.39.0/go.mod h1:jrZSWL33sD7bBxg1xjrqyDjnuzTUB0x1nBERXd7Ftcs=
-go.opentelemetry.io/otel/sdk v1.39.0 h1:nMLYcjVsvdui1B/4FRkwjzoRVsMK8uL/cj0OyhKzt18=
-go.opentelemetry.io/otel/sdk v1.39.0/go.mod h1:vDojkC4/jsTJsE+kh+LXYQlbL8CgrEcwmt1ENZszdJE=
-go.opentelemetry.io/otel/sdk/metric v1.39.0 h1:cXMVVFVgsIf2YL6QkRF4Urbr/aMInf+2WKg+sEJTtB8=
-go.opentelemetry.io/otel/sdk/metric v1.39.0/go.mod h1:xq9HEVH7qeX69/JnwEfp6fVq5wosJsY1mt4lLfYdVew=
-go.opentelemetry.io/otel/trace v1.39.0 h1:2d2vfpEDmCJ5zVYz7ijaJdOF59xLomrvj7bjt6/qCJI=
-go.opentelemetry.io/otel/trace v1.39.0/go.mod h1:88w4/PnZSazkGzz/w84VHpQafiU4EtqqlVdxWy+rNOA=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
+go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
 golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
@@ -141,8 +143,8 @@ golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
-golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
@@ -170,8 +172,8 @@ google.golang.org/genproto/googleapis/api v0.0.0-20260128011058-8636f8732409 h1:
 google.golang.org/genproto/googleapis/api v0.0.0-20260128011058-8636f8732409/go.mod h1:fl8J1IvUjCilwZzQowmw2b7HQB2eAuYBabMXzWurF+I=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20260217215200-42d3e9bedb6d h1:t/LOSXPJ9R0B6fnZNyALBRfZBH0Uy0gT+uR+SJ6syqQ=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20260217215200-42d3e9bedb6d/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.79.1 h1:zGhSi45ODB9/p3VAawt9a+O/MULLl9dpizzNNpq7flY=
-google.golang.org/grpc v1.79.1/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
+google.golang.org/grpc v1.79.3 h1:sybAEdRIEtvcD68Gx7dmnwjZKlyfuc61Dyo9pGXXkKE=
+google.golang.org/grpc v1.79.3/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.30.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=

backend/infra/migrations/003_add_slack_webhook.sql

@@ -0,0 +1,2 @@
+ALTER TABLE user_notification_configs
+  ADD COLUMN IF NOT EXISTS slack_webhook_url TEXT;

backend/infra/migrations/004_alert_event_dedup.sql

@@ -0,0 +1,3 @@
+CREATE UNIQUE INDEX IF NOT EXISTS idx_alert_events_dedup
+    ON alert_events (alert_rule_id, tx_hash)
+    WHERE tx_hash IS NOT NULL;

backend/infra/migrations/005_create_users_table.sql

@@ -0,0 +1,13 @@
+-- Migration 005: Create users table with UUID primary key
+-- This establishes a local user record for each Firebase-authenticated user.
+
+CREATE TABLE IF NOT EXISTS users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  firebase_uid VARCHAR(128) NOT NULL UNIQUE,
+  email VARCHAR(255) NOT NULL,
+  display_name VARCHAR(255),
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_users_firebase_uid ON users(firebase_uid);

backend/infra/migrations/006_migrate_user_ids_to_uuid.sql

@@ -0,0 +1,73 @@
+-- Migration 006: Migrate user_id columns from Firebase UID strings to user UUIDs
+--
+-- Prerequisites: migration 005 (users table) must be applied first.
+-- This migration backfills the users table from existing data, then swaps the
+-- VARCHAR user_id columns for UUID foreign keys referencing users(id).
+
+BEGIN;
+
+-- 1. Backfill users table from existing Firebase UIDs in addresses
+INSERT INTO users (firebase_uid, email)
+  SELECT DISTINCT user_id, ''
+  FROM addresses
+  WHERE user_id IS NOT NULL
+ON CONFLICT (firebase_uid) DO NOTHING;
+
+-- 2. Backfill from notification configs (catches users with configs but no addresses)
+INSERT INTO users (firebase_uid, email)
+  SELECT DISTINCT user_id, ''
+  FROM user_notification_configs
+  WHERE user_id IS NOT NULL
+ON CONFLICT (firebase_uid) DO NOTHING;
+
+-- ============================================================
+-- 3. Migrate addresses.user_id from VARCHAR to UUID
+-- ============================================================
+
+ALTER TABLE addresses ADD COLUMN user_uuid UUID;
+
+UPDATE addresses a
+SET user_uuid = u.id
+FROM users u
+WHERE u.firebase_uid = a.user_id;
+
+-- Drop old constraints and column
+ALTER TABLE addresses DROP CONSTRAINT IF EXISTS addresses_user_id_address_key;
+DROP INDEX IF EXISTS idx_addresses_user_id;
+ALTER TABLE addresses DROP COLUMN user_id;
+
+-- Rename and constrain
+ALTER TABLE addresses RENAME COLUMN user_uuid TO user_id;
+ALTER TABLE addresses ALTER COLUMN user_id SET NOT NULL;
+ALTER TABLE addresses ADD CONSTRAINT fk_addresses_user
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE;
+ALTER TABLE addresses ADD CONSTRAINT addresses_user_id_address_key
+  UNIQUE (user_id, address);
+CREATE INDEX idx_addresses_user_id ON addresses(user_id);
+
+-- ============================================================
+-- 4. Migrate user_notification_configs.user_id from VARCHAR to UUID
+-- ============================================================
+
+-- Drop the PK first (it's on user_id)
+ALTER TABLE user_notification_configs DROP CONSTRAINT IF EXISTS user_notification_configs_pkey;
+DROP INDEX IF EXISTS idx_notification_configs_enabled;
+
+ALTER TABLE user_notification_configs ADD COLUMN user_uuid UUID;
+
+UPDATE user_notification_configs nc
+SET user_uuid = u.id
+FROM users u
+WHERE u.firebase_uid = nc.user_id;
+
+ALTER TABLE user_notification_configs DROP COLUMN user_id;
+ALTER TABLE user_notification_configs RENAME COLUMN user_uuid TO user_id;
+ALTER TABLE user_notification_configs ALTER COLUMN user_id SET NOT NULL;
+ALTER TABLE user_notification_configs ADD CONSTRAINT user_notification_configs_pkey
+  PRIMARY KEY (user_id);
+ALTER TABLE user_notification_configs ADD CONSTRAINT fk_notification_configs_user
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE;
+CREATE INDEX idx_notification_configs_enabled
+  ON user_notification_configs(notification_enabled);
+
+COMMIT;

backend/infra/migrations/007_add_stripe_to_users.sql

@@ -0,0 +1,8 @@
+-- Migration 007: Add Stripe subscription fields to users table
+
+ALTER TABLE users ADD COLUMN IF NOT EXISTS stripe_customer_id VARCHAR(255);
+ALTER TABLE users ADD COLUMN IF NOT EXISTS stripe_subscription_id VARCHAR(255);
+ALTER TABLE users ADD COLUMN IF NOT EXISTS subscription_status VARCHAR(50) DEFAULT 'none';
+ALTER TABLE users ADD COLUMN IF NOT EXISTS subscription_created_at TIMESTAMP;
+
+CREATE INDEX IF NOT EXISTS idx_users_stripe_customer_id ON users(stripe_customer_id);

backend/infra/migrations/008_add_min_max_to_alert_rules.sql

@@ -0,0 +1,6 @@
+ALTER TABLE alert_rules ADD COLUMN minimum DECIMAL(20, 6);
+ALTER TABLE alert_rules ADD COLUMN maximum DECIMAL(20, 6);
+
+ALTER TABLE alert_rules ADD CONSTRAINT non_negative_minimum CHECK (minimum IS NULL OR minimum >= 0);
+ALTER TABLE alert_rules ADD CONSTRAINT non_negative_maximum CHECK (maximum IS NULL OR maximum >= 0);
+ALTER TABLE alert_rules ADD CONSTRAINT min_lte_max CHECK (minimum IS NULL OR maximum IS NULL OR minimum <= maximum);

backend/infra/migrations/009_add_subscription_tier.sql

@@ -0,0 +1,8 @@
+ALTER TABLE users ADD COLUMN IF NOT EXISTS subscription_tier VARCHAR(20) DEFAULT 'free';
+
+-- Existing active/trialing subscribers were on the single paid plan,
+-- which is now the "premium" tier. Backfill them so they aren't downgraded.
+UPDATE users
+SET subscription_tier = 'premium'
+WHERE subscription_status IN ('active', 'trialing')
+  AND stripe_subscription_id IS NOT NULL;

backend/infra/migrations/010_add_unique_email_index.sql

@@ -0,0 +1,20 @@
+-- Migration 010: enforce unique emails in users
+-- Matches runtime expectation for idx_users_email_unique.
+
+BEGIN;
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1
+    FROM users
+    GROUP BY email
+    HAVING COUNT(*) > 1
+  ) THEN
+    RAISE EXCEPTION 'Cannot create unique index idx_users_email_unique: duplicate emails exist in users';
+  END IF;
+END $$;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_users_email_unique ON users(email);
+
+COMMIT;

backend/infra/schema.sql

@@ -4,15 +4,29 @@ DROP TABLE IF EXISTS alert_rules CASCADE;
 DROP TABLE IF EXISTS address_checkpoints CASCADE;
 DROP TABLE IF EXISTS user_notification_configs CASCADE;
 DROP TABLE IF EXISTS addresses CASCADE;
+DROP TABLE IF EXISTS users CASCADE;
+
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  firebase_uid VARCHAR(128) NOT NULL UNIQUE,
+  email VARCHAR(255) NOT NULL,
+  display_name VARCHAR(255),
+  stripe_customer_id VARCHAR(255),
+  stripe_subscription_id VARCHAR(255),
+  subscription_status VARCHAR(50) DEFAULT 'none',
+  subscription_tier VARCHAR(20) DEFAULT 'free',
+  subscription_created_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
 
 CREATE TABLE addresses (
   id SERIAL PRIMARY KEY,
-  user_id VARCHAR(128) NOT NULL,       -- Firebase user ID (multi-user support)
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
   address VARCHAR(42) NOT NULL,        -- Ethereum address format (0x + 40 hex chars)
   label VARCHAR(255),                  -- Optional human-readable label
   created_at TIMESTAMP DEFAULT NOW(),
 
-  -- Unique users can track the same address independently
   UNIQUE(user_id, address)
 );
 
@@ -22,6 +36,8 @@ CREATE TABLE alert_rules (
   address_id INTEGER NOT NULL REFERENCES addresses(id) ON DELETE CASCADE,
   type VARCHAR(50) NOT NULL,           -- 'incoming_tx', 'outgoing_tx', 'large_transfer', 'balance_below'
   threshold DECIMAL(20, 6),            -- ETH amount threshold (nullable for tx types that don't need it)
+  minimum DECIMAL(20, 6),              -- Optional min amount filter for incoming/outgoing alerts
+  maximum DECIMAL(20, 6),              -- Optional max amount filter for incoming/outgoing alerts
   enabled BOOLEAN DEFAULT TRUE,
   created_at TIMESTAMP DEFAULT NOW(),
 
@@ -31,7 +47,11 @@ CREATE TABLE alert_rules (
 
   CONSTRAINT positive_threshold CHECK (
     threshold IS NULL OR threshold > 0
-  )
+  ),
+
+  CONSTRAINT non_negative_minimum CHECK (minimum IS NULL OR minimum >= 0),
+  CONSTRAINT non_negative_maximum CHECK (maximum IS NULL OR maximum >= 0),
+  CONSTRAINT min_lte_max CHECK (minimum IS NULL OR maximum IS NULL OR minimum <= maximum)
 );
 
 
@@ -51,17 +71,20 @@ CREATE TABLE address_checkpoints (
 );
 
 CREATE TABLE user_notification_configs (
-  user_id VARCHAR(128) PRIMARY KEY,
+  user_id UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
   discord_webhook_url TEXT,            -- Discord webhook URL (nullable)
   telegram_chat_id VARCHAR(128),       -- Telegram chat ID (nullable)
-  telegram_bot_token VARCHAR(255),     -- Telegram bot token (nullable, future use)
+  telegram_bot_token VARCHAR(255),     -- Telegram bot token (nullable)
   email VARCHAR(255),                  -- Email for notifications (nullable)
+  slack_webhook_url TEXT,              -- Slack incoming webhook URL (nullable)
   notification_enabled BOOLEAN DEFAULT TRUE,  -- Master on/off switch
   created_at TIMESTAMP DEFAULT NOW(),
   updated_at TIMESTAMP DEFAULT NOW()
 );
 
 -- Create indexes for common queries
+CREATE INDEX idx_users_firebase_uid ON users(firebase_uid);
+CREATE INDEX idx_users_stripe_customer_id ON users(stripe_customer_id);
 CREATE INDEX idx_addresses_user_id ON addresses(user_id);
 CREATE INDEX idx_alert_rules_address_id ON alert_rules(address_id);
 CREATE INDEX idx_alert_rules_enabled ON alert_rules(enabled);

backend/internal/config/config.go

@@ -0,0 +1,135 @@
+// loads environment-based configuration.
+package config
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+)
+
+const (
+	defaultPort                = 3001
+	defaultDBPort              = 5432
+	defaultPollIntervalMS      = 60000
+	minPollIntervalMS          = 1000
+	defaultDigestIntervalHours = 24
+)
+
+type Config struct {
+	Port                       int
+	APIBasePath                string
+	DatabaseURL                string
+	DBHost                     string
+	DBPort                     int
+	DBUser                     string
+	DBPassword                 string
+	DBName                     string
+	FirebaseProjectID          string
+	EthRPCURL                  string
+	PollIntervalMS             int
+	NodeEnv                    string
+	ResendAPIKey               string
+	EmailFrom                  string
+	SupportInboxEmail          string
+	DigestIntervalHours        int
+	StripeSecretKey            string
+	StripeWebhookSecret        string
+	StripePriceIDPremium       string
+	StripePriceIDPro           string
+	StripePriceIDPremiumAnnual string
+	StripePriceIDProAnnual     string
+	StripePublishableKey       string
+	FrontendURL                string
+}
+
+// Load reads configuration from environment variables and returns a Config.
+func Load() (*Config, error) {
+	cfg := &Config{
+		Port:                       getEnvInt("PORT", defaultPort),
+		APIBasePath:                getEnv("API_BASE_PATH", "/v1"),
+		DatabaseURL:                os.Getenv("DATABASE_URL"),
+		DBHost:                     getEnv("DB_HOST", "localhost"),
+		DBPort:                     getEnvInt("DB_PORT", defaultDBPort),
+		DBUser:                     os.Getenv("DB_USER"),
+		DBPassword:                 os.Getenv("DB_PASSWORD"),
+		DBName:                     os.Getenv("DB_NAME"),
+		FirebaseProjectID:          os.Getenv("FIREBASE_PROJECT_ID"),
+		EthRPCURL:                  os.Getenv("ETH_RPC_URL"),
+		PollIntervalMS:             getEnvInt("POLL_INTERVAL_MS", defaultPollIntervalMS),
+		NodeEnv:                    getEnv("NODE_ENV", "development"),
+		ResendAPIKey:               os.Getenv("RESEND_API_KEY"),
+		EmailFrom:                  getEnv("EMAIL_FROM", "Koin Ping <alerts@koinping.com>"),
+		SupportInboxEmail:          getEnv("SUPPORT_INBOX_EMAIL", "sj@sjdev.co"),
+		DigestIntervalHours:        getEnvInt("DIGEST_INTERVAL_HOURS", defaultDigestIntervalHours),
+		StripeSecretKey:            os.Getenv("STRIPE_SECRET_KEY"),
+		StripeWebhookSecret:        os.Getenv("STRIPE_WEBHOOK_SECRET"),
+		StripePriceIDPremium:       os.Getenv("STRIPE_PRICE_ID_PREMIUM"),
+		StripePriceIDPro:           os.Getenv("STRIPE_PRICE_ID_PRO"),
+		StripePriceIDPremiumAnnual: os.Getenv("STRIPE_PRICE_ID_PREMIUM_ANNUAL"),
+		StripePriceIDProAnnual:     os.Getenv("STRIPE_PRICE_ID_PRO_ANNUAL"),
+		StripePublishableKey:       os.Getenv("STRIPE_PUBLISHABLE_KEY"),
+		FrontendURL:                getEnv("FRONTEND_URL", "http://localhost:3000"),
+	}
+
+	if cfg.PollIntervalMS < minPollIntervalMS {
+		return nil, fmt.Errorf("POLL_INTERVAL_MS must be >= 1000, got %d", cfg.PollIntervalMS) //nolint:err113
+	}
+
+	return cfg, nil
+}
+
+func (c *Config) DSN() string {
+	if c.DatabaseURL != "" {
+		// Append sslmode=disable if not already specified.
+		if !strings.Contains(c.DatabaseURL, "sslmode=") {
+			sep := "?"
+			if strings.Contains(c.DatabaseURL, "?") {
+				sep = "&"
+			}
+
+			return c.DatabaseURL + sep + "sslmode=disable"
+		}
+
+		return c.DatabaseURL
+	}
+
+	return fmt.Sprintf(
+		"host=%s port=%d user=%s password=%s dbname=%s sslmode=disable",
+		c.DBHost, c.DBPort, c.DBUser, c.DBPassword, c.DBName,
+	)
+}
+
+// TierForPriceID maps a Stripe price ID back to the corresponding
+// subscription tier. Returns empty string if the price is unrecognised.
+func (c *Config) TierForPriceID(priceID string) string {
+	if priceID == "" {
+		return ""
+	}
+	switch priceID {
+	case c.StripePriceIDPremium, c.StripePriceIDPremiumAnnual:
+		return "premium"
+	case c.StripePriceIDPro, c.StripePriceIDProAnnual:
+		return "pro"
+	default:
+		return ""
+	}
+}
+
+func getEnv(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+
+	return fallback
+}
+
+func getEnvInt(key string, fallback int) int {
+	if v := os.Getenv(key); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			return n
+		}
+	}
+
+	return fallback
+}

backend/internal/config/config_test.go

@@ -0,0 +1,32 @@
+package config
+
+import "testing"
+
+func TestTierForPriceID(t *testing.T) {
+	t.Parallel()
+
+	cfg := &Config{
+		StripePriceIDPremium:       "price_premium_123",
+		StripePriceIDPro:           "price_pro_456",
+		StripePriceIDPremiumAnnual: "price_premium_yr",
+		StripePriceIDProAnnual:     "price_pro_yr",
+	}
+
+	tests := []struct {
+		priceID string
+		want    string
+	}{
+		{"price_premium_123", "premium"},
+		{"price_pro_456", "pro"},
+		{"price_premium_yr", "premium"},
+		{"price_pro_yr", "pro"},
+		{"price_unknown", ""},
+		{"", ""},
+	}
+
+	for _, tt := range tests {
+		if got := cfg.TierForPriceID(tt.priceID); got != tt.want {
+			t.Errorf("TierForPriceID(%q) = %q, want %q", tt.priceID, got, tt.want)
+		}
+	}
+}

backend/internal/database/postgres.go

@@ -1,4 +1,3 @@
-// Package database manages PostgreSQL connection pools.
 package database
 
 import (
@@ -11,21 +10,21 @@ import (
 )
 
 const (
-	// maxConnIdleSeconds is the maximum idle time for a connection.
+
 	maxConnIdleSeconds = 30
-	// maxConnLifetimeMinutes is the maximum lifetime for a connection.
+
 	maxConnLifetimeMinutes = 5
-	// connectTimeoutSeconds is the timeout for initial connection.
+
 	connectTimeoutSeconds = 10
-	// maxConns is the maximum number of connections in the pool.
+
 	maxConns = 20
-	// minConns is the minimum number of connections in the pool.
+
 	minConns = 2
 )
 
 var pool *pgxpool.Pool //nolint:gochecknoglobals
 
-// Connect establishes a PostgreSQL connection pool using the given DSN.
+// establishPostgreSQL connection pool using the given DSN.
 func Connect(dsn string) (*pgxpool.Pool, error) {
 	cfg, err := pgxpool.ParseConfig(dsn)
 	if err != nil {
@@ -57,12 +56,10 @@ func Connect(dsn string) (*pgxpool.Pool, error) {
 	return p, nil
 }
 
-// Pool returns the global connection pool.
 func Pool() *pgxpool.Pool {
 	return pool
 }
 
-// Close closes the global connection pool.
 func Close() {
 	if pool != nil {
 		pool.Close()

backend/internal/domain/types.go

@@ -1,9 +1,80 @@
-// Package domain defines core domain types shared across the application.
 package domain
 
 import "time"
 
-// Address represents a tracked Ethereum address.
+type SubscriptionTier string
+
+const (
+	TierFree    SubscriptionTier = "free"
+	TierPremium SubscriptionTier = "premium"
+	TierPro     SubscriptionTier = "pro"
+)
+
+func IsValidTier(t string) bool {
+	switch SubscriptionTier(t) {
+	case TierFree, TierPremium, TierPro:
+		return true
+	}
+	return false
+}
+
+const unlimitedLimit = -1
+
+type TierLimits struct {
+	MaxAddresses    int      `json:"max_addresses"`
+	MaxAlertTypes   int      `json:"max_alert_types"`
+	AllowedChannels []string `json:"allowed_channels"`
+}
+
+func GetTierLimits(tier SubscriptionTier) TierLimits {
+	switch tier {
+	case TierPremium:
+		return TierLimits{
+			MaxAddresses:    3,
+			MaxAlertTypes:   2,
+			AllowedChannels: []string{"email", "discord", "telegram"},
+		}
+	case TierPro:
+		return TierLimits{
+			MaxAddresses:    unlimitedLimit,
+			MaxAlertTypes:   unlimitedLimit,
+			AllowedChannels: []string{"email", "discord", "telegram", "slack"},
+		}
+	default:
+		return TierLimits{
+			MaxAddresses:    1,
+			MaxAlertTypes:   1,
+			AllowedChannels: []string{"email"},
+		}
+	}
+}
+
+func (l TierLimits) IsUnlimitedAddresses() bool  { return l.MaxAddresses == unlimitedLimit }
+func (l TierLimits) IsUnlimitedAlertTypes() bool  { return l.MaxAlertTypes == unlimitedLimit }
+
+func (l TierLimits) ChannelAllowed(channel string) bool {
+	for _, c := range l.AllowedChannels {
+		if c == channel {
+			return true
+		}
+	}
+	return false
+}
+
+type User struct {
+	ID                    string           `json:"id"`
+	FirebaseUID           string           `json:"-"`
+	Email                 string           `json:"email"`
+	DisplayName           *string          `json:"display_name"`           //nolint:tagliatelle
+	StripeCustomerID      *string          `json:"-"`
+	StripeSubscriptionID  *string          `json:"-"`
+	SubscriptionStatus    string           `json:"subscription_status"`    //nolint:tagliatelle
+	SubscriptionTier      SubscriptionTier `json:"subscription_tier"`      //nolint:tagliatelle
+	SubscriptionCreatedAt *time.Time       `json:"subscription_created_at,omitempty"` //nolint:tagliatelle
+	CreatedAt             time.Time        `json:"created_at"`             //nolint:tagliatelle
+	UpdatedAt             time.Time        `json:"updated_at"`             //nolint:tagliatelle
+}
+
 type Address struct {
 	ID        int       `json:"id"`
 	UserID    string    `json:"user_id"`    //nolint:tagliatelle
@@ -12,13 +83,10 @@ type Address struct {
 	CreatedAt time.Time `json:"created_at"` //nolint:tagliatelle
 }
 
-// AlertType identifies the kind of alert rule.
 type AlertType string
 
-// String implements fmt.Stringer.
 func (a AlertType) String() string { return string(a) }
 
-// Alert type constants define the supported alert triggers.
 const (
 	AlertIncomingTx    AlertType = "incoming_tx"
 	AlertOutgoingTx    AlertType = "outgoing_tx"
@@ -26,7 +94,6 @@ const (
 	AlertBalanceBelow  AlertType = "balance_below"
 )
 
-// ValidAlertTypes lists all alert types accepted by the API.
 var ValidAlertTypes = []AlertType{ //nolint:gochecknoglobals
 	AlertIncomingTx,
 	AlertOutgoingTx,
@@ -40,7 +107,7 @@ var ThresholdRequiredTypes = []AlertType{ //nolint:gochecknoglobals
 	AlertBalanceBelow,
 }
 
-// IsValidAlertType returns true if the given string matches a known AlertType.
+// returns true if the given string matches a known AlertType.
 func IsValidAlertType(t string) bool {
 	for _, v := range ValidAlertTypes {
 		if string(v) == t {
@@ -51,7 +118,6 @@ func IsValidAlertType(t string) bool {
 	return false
 }
 
-// IsThresholdRequired returns true if the given AlertType requires a threshold.
 func IsThresholdRequired(t AlertType) bool {
 	for _, v := range ThresholdRequiredTypes {
 		if v == t {
@@ -62,17 +128,17 @@ func IsThresholdRequired(t AlertType) bool {
 	return false
 }
 
-// AlertRule represents a user-defined alert rule for an address.
 type AlertRule struct {
 	ID        int       `json:"id"`
 	AddressID int       `json:"address_id"` //nolint:tagliatelle
 	Type      AlertType `json:"type"`
 	Threshold *float64  `json:"threshold"`
+	Minimum   *float64  `json:"minimum"`
+	Maximum   *float64  `json:"maximum"`
 	Enabled   bool      `json:"enabled"`
 	CreatedAt time.Time `json:"created_at"` //nolint:tagliatelle
 }
 
-// AlertEvent represents a fired alert event stored for history.
 type AlertEvent struct {
 	ID           int       `json:"id"`
 	AlertRuleID  int       `json:"alert_rule_id"`   //nolint:tagliatelle
@@ -82,14 +148,12 @@ type AlertEvent struct {
 	Timestamp    time.Time `json:"timestamp"`
 }
 
-// AddressCheckpoint tracks the last block checked for an address.
 type AddressCheckpoint struct {
 	AddressID        int       `json:"address_id"`         //nolint:tagliatelle
 	LastCheckedBlock int       `json:"last_checked_block"` //nolint:tagliatelle
 	LastCheckedAt    time.Time `json:"last_checked_at"`    //nolint:tagliatelle
 }
 
-// CheckpointDetail combines checkpoint and address info for reporting.
 type CheckpointDetail struct {
 	AddressID        int       `json:"address_id"`         //nolint:tagliatelle
 	Address          string    `json:"address"`
@@ -98,13 +162,14 @@ type CheckpointDetail struct {
 	LastCheckedAt    time.Time `json:"last_checked_at"`    //nolint:tagliatelle
 }
 
-// NotificationConfig holds a user's notification preferences.
+//  holds a user's notification preferences.
 type NotificationConfig struct {
 	UserID              string     `json:"user_id"`              //nolint:tagliatelle
 	DiscordWebhookURL   *string    `json:"discord_webhook_url"`  //nolint:tagliatelle
 	TelegramChatID      *string    `json:"telegram_chat_id"`     //nolint:tagliatelle
-	TelegramBotToken    *string    `json:"telegram_bot_token,omitempty"` //nolint:tagliatelle
+	TelegramBotToken    *string    `json:"telegram_bot_token"`   //nolint:tagliatelle
 	Email               *string    `json:"email"`
+	SlackWebhookURL     *string    `json:"slack_webhook_url"`    //nolint:tagliatelle
 	NotificationEnabled bool       `json:"notification_enabled"` //nolint:tagliatelle
 	CreatedAt           *time.Time `json:"created_at,omitempty"` //nolint:tagliatelle
 	UpdatedAt           *time.Time `json:"updated_at,omitempty"` //nolint:tagliatelle
@@ -118,21 +183,27 @@ type NormalizedTx struct {
 	Value          string  `json:"value"` // Wei as string for precision
 	BlockNumber    int     `json:"block_number"`    //nolint:tagliatelle
 	BlockTimestamp int64   `json:"block_timestamp"` //nolint:tagliatelle
+
+	// ERC-20 token transfer fields (nil for native ETH transfers)
+	TokenContract *string `json:"token_contract,omitempty"` //nolint:tagliatelle
+	TokenSymbol   *string `json:"token_symbol,omitempty"`   //nolint:tagliatelle
+	TokenDecimals *int    `json:"token_decimals,omitempty"` //nolint:tagliatelle
+	TokenValue    *string `json:"token_value,omitempty"`    //nolint:tagliatelle
+}
+
+func (tx NormalizedTx) IsTokenTransfer() bool {
+	return tx.TokenContract != nil
 }
 
-// Direction indicates whether a transaction is incoming or outgoing.
 type Direction string
 
-// String implements fmt.Stringer.
 func (d Direction) String() string { return string(d) }
 
-// Direction constants indicate the flow of a transaction relative to a watched address.
 const (
 	DirectionIncoming Direction = "incoming"
 	DirectionOutgoing Direction = "outgoing"
 )
 
-// ObservedTx is a NormalizedTx enriched with address and direction context.
 type ObservedTx struct {
 	NormalizedTx
 	AddressID int       `json:"address_id"` //nolint:tagliatelle

backend/internal/domain/types_test.go

@@ -0,0 +1,104 @@
+package domain
+
+import "testing"
+
+func TestIsValidTier(t *testing.T) {
+	t.Parallel()
+
+	valid := []string{"free", "premium", "pro"}
+	for _, tier := range valid {
+		if !IsValidTier(tier) {
+			t.Errorf("expected %q to be valid", tier)
+		}
+	}
+
+	invalid := []string{"", "basic", "enterprise", "FREE", "Pro"}
+	for _, tier := range invalid {
+		if IsValidTier(tier) {
+			t.Errorf("expected %q to be invalid", tier)
+		}
+	}
+}
+
+func TestGetTierLimits_Free(t *testing.T) {
+	t.Parallel()
+
+	limits := GetTierLimits(TierFree)
+	if limits.MaxAddresses != 1 {
+		t.Errorf("free MaxAddresses = %d, want 1", limits.MaxAddresses)
+	}
+	if limits.MaxAlertTypes != 1 {
+		t.Errorf("free MaxAlertTypes = %d, want 1", limits.MaxAlertTypes)
+	}
+	if len(limits.AllowedChannels) != 1 || limits.AllowedChannels[0] != "email" {
+		t.Errorf("free AllowedChannels = %v, want [email]", limits.AllowedChannels)
+	}
+	if limits.IsUnlimitedAddresses() {
+		t.Error("free should not have unlimited addresses")
+	}
+	if limits.IsUnlimitedAlertTypes() {
+		t.Error("free should not have unlimited alert types")
+	}
+}
+
+func TestGetTierLimits_Premium(t *testing.T) {
+	t.Parallel()
+
+	limits := GetTierLimits(TierPremium)
+	if limits.MaxAddresses != 3 {
+		t.Errorf("premium MaxAddresses = %d, want 3", limits.MaxAddresses)
+	}
+	if limits.MaxAlertTypes != 2 {
+		t.Errorf("premium MaxAlertTypes = %d, want 2", limits.MaxAlertTypes)
+	}
+	if !limits.ChannelAllowed("email") {
+		t.Error("premium should allow email")
+	}
+	if !limits.ChannelAllowed("discord") {
+		t.Error("premium should allow discord")
+	}
+	if !limits.ChannelAllowed("telegram") {
+		t.Error("premium should allow telegram")
+	}
+	if limits.ChannelAllowed("slack") {
+		t.Error("premium should NOT allow slack")
+	}
+}
+
+func TestGetTierLimits_Pro(t *testing.T) {
+	t.Parallel()
+
+	limits := GetTierLimits(TierPro)
+	if !limits.IsUnlimitedAddresses() {
+		t.Error("pro should have unlimited addresses")
+	}
+	if !limits.IsUnlimitedAlertTypes() {
+		t.Error("pro should have unlimited alert types")
+	}
+	for _, ch := range []string{"email", "discord", "telegram", "slack"} {
+		if !limits.ChannelAllowed(ch) {
+			t.Errorf("pro should allow %s", ch)
+		}
+	}
+}
+
+func TestGetTierLimits_Unknown(t *testing.T) {
+	t.Parallel()
+
+	limits := GetTierLimits(SubscriptionTier("unknown"))
+	if limits.MaxAddresses != 1 {
+		t.Errorf("unknown tier should default to free limits, got MaxAddresses=%d", limits.MaxAddresses)
+	}
+}
+
+func TestChannelAllowed_NotInList(t *testing.T) {
+	t.Parallel()
+
+	limits := GetTierLimits(TierFree)
+	if limits.ChannelAllowed("discord") {
+		t.Error("free should not allow discord")
+	}
+	if limits.ChannelAllowed("nonexistent") {
+		t.Error("nonexistent channel should not be allowed")
+	}
+}

backend/internal/firebase/admin.go

@@ -1,4 +1,3 @@
-// Package firebase provides Firebase authentication integration.
 package firebase
 
 import (
@@ -17,7 +16,6 @@ var ( //nolint:gochecknoglobals
 	errInit    error        //nolint:gochecknoglobals
 )
 
-// Init initializes the Firebase app and auth client using the given project ID.
 func Init(projectID string) error {
 	once.Do(func() {
 		ctx := context.Background()
@@ -48,7 +46,6 @@ func Init(projectID string) error {
 	return errInit
 }
 
-// Auth returns the initialized Firebase auth client.
 func Auth() *auth.Client {
 	return authClient
 }

backend/internal/firebase/users.go

@@ -0,0 +1,22 @@
+package firebase
+
+import (
+	"context"
+	"fmt"
+
+	"firebase.google.com/go/v4/auth"
+)
+
+// SetUserDisabled updates the Firebase user record's disabled flag.
+func SetUserDisabled(ctx context.Context, uid string, disabled bool) error {
+	if authClient == nil {
+		return fmt.Errorf("firebase auth not initialized") //nolint:err113
+	}
+	if uid == "" {
+		return nil
+	}
+
+	params := (&auth.UserToUpdate{}).Disabled(disabled)
+	_, err := authClient.UpdateUser(ctx, uid, params)
+	return err
+}

backend/internal/handlers/account.go

@@ -0,0 +1,88 @@
+package handlers
+
+import (
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/kjannette/koin-ping/backend/internal/config"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/middleware"
+	"github.com/kjannette/koin-ping/backend/internal/models"
+)
+
+type AccountHandler struct {
+	users     *models.UserModel
+	addresses *models.AddressModel
+	cfg       *config.Config
+}
+
+func NewAccountHandler(users *models.UserModel, addresses *models.AddressModel, cfg *config.Config) *AccountHandler {
+	return &AccountHandler{users: users, addresses: addresses, cfg: cfg}
+}
+
+type accountResponse struct {
+	UserID             string            `json:"user_id"`
+	Email              string            `json:"email"`
+	UserName           string            `json:"user_name"`
+	SubscriptionStatus string            `json:"subscription_status"`
+	SubscriptionTier   string            `json:"subscription_tier"`
+	SubscriptionPlan   string            `json:"subscription_plan"`
+	TierLimits         domain.TierLimits `json:"tier_limits"`
+	AddressCount       int               `json:"address_count"`
+	MemberSince        *string           `json:"member_since,omitempty"`
+	NextBillingDate    *string           `json:"next_billing_date,omitempty"`
+	CancelAtPeriodEnd  bool              `json:"cancel_at_period_end"`
+	PeriodEndDate      *string           `json:"period_end_date,omitempty"`
+}
+
+var tierPlanLabels = map[domain.SubscriptionTier]string{ //nolint:gochecknoglobals
+	domain.TierFree:    "Free Trial",
+	domain.TierPremium: "Premium / $8.78 mo",
+	domain.TierPro:     "Pro / $16.78 mo",
+}
+
+func (h *AccountHandler) GetAccount(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+	email := middleware.GetUserEmail(r.Context())
+
+	user, err := h.users.GetByID(r.Context(), userID)
+	if err != nil || user == nil {
+		log.Printf("Account: failed to get user %s: %v", userID, err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to load user")
+		return
+	}
+
+	addrCount, err := h.addresses.CountByUser(r.Context(), userID)
+	if err != nil {
+		log.Printf("Account: failed to count addresses for %s: %v", userID, err)
+		addrCount = 0
+	}
+
+	planLabel := tierPlanLabels[user.SubscriptionTier]
+	if planLabel == "" {
+		planLabel = "Free Trial"
+	}
+
+	resp := accountResponse{
+		UserID:             user.ID,
+		Email:              email,
+		UserName:           email,
+		SubscriptionStatus: user.SubscriptionStatus,
+		SubscriptionTier:   string(user.SubscriptionTier),
+		SubscriptionPlan:   planLabel,
+		TierLimits:         domain.GetTierLimits(user.SubscriptionTier),
+		AddressCount:       addrCount,
+	}
+
+	if user.SubscriptionCreatedAt != nil {
+		t := user.SubscriptionCreatedAt.Format(time.DateOnly)
+		resp.MemberSince = &t
+	}
+
+	resp.NextBillingDate = nil
+	resp.CancelAtPeriodEnd = false
+	resp.PeriodEndDate = nil
+
+	writeJSON(w, http.StatusOK, resp)
+}

backend/internal/handlers/address.go

@@ -3,29 +3,28 @@ package handlers
 
 import (
 	"encoding/json"
+	"fmt"
 	"log"
 	"net/http"
 	"regexp"
 	"strings"
 
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
-	"github.com/kjannette/koin-ping/backend-go/internal/middleware"
-	"github.com/kjannette/koin-ping/backend-go/internal/models"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/middleware"
+	"github.com/kjannette/koin-ping/backend/internal/models"
 )
 
 var ethAddressRe = regexp.MustCompile(`^0x[a-fA-F0-9]{40}$`)
 
-// AddressHandler handles HTTP requests for address management.
 type AddressHandler struct {
 	addresses *models.AddressModel
+	users     *models.UserModel
 }
 
-// NewAddressHandler creates a new AddressHandler.
-func NewAddressHandler(addresses *models.AddressModel) *AddressHandler {
-	return &AddressHandler{addresses: addresses}
+func NewAddressHandler(addresses *models.AddressModel, users *models.UserModel) *AddressHandler {
+	return &AddressHandler{addresses: addresses, users: users}
 }
 
-// Create handles POST requests to add a new tracked address.
 func (h *AddressHandler) Create(w http.ResponseWriter, r *http.Request) {
 	userID := middleware.GetUserID(r.Context())
 
@@ -52,6 +51,28 @@ func (h *AddressHandler) Create(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	user, err := h.users.GetByID(r.Context(), userID)
+	if err != nil || user == nil {
+		log.Printf("Failed to get user %s for tier check: %v", userID, err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to verify account")
+		return
+	}
+
+	limits := domain.GetTierLimits(user.SubscriptionTier)
+	if !limits.IsUnlimitedAddresses() {
+		count, err := h.addresses.CountByUser(r.Context(), userID)
+		if err != nil {
+			log.Printf("Failed to count addresses for user %s: %v", userID, err)
+			writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to create address")
+			return
+		}
+		if count >= limits.MaxAddresses {
+			writeError(w, http.StatusForbidden, "TIER_LIMIT_REACHED",
+				fmt.Sprintf("Your %s plan allows %d address(es). Upgrade to track more.", user.SubscriptionTier, limits.MaxAddresses))
+			return
+		}
+	}
+
 	log.Printf("User %s creating address: %s", userID, body.Address)
 
 	addr, err := h.addresses.Create(r.Context(), userID, body.Address, body.Label)
@@ -92,6 +113,44 @@ func (h *AddressHandler) List(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, addresses)
 }
 
+//  handles PATCH requests to update an address label.
+func (h *AddressHandler) UpdateLabel(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+	addressID, ok := parseIntParam(r.PathValue("addressId"))
+	if !ok {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "Invalid address ID")
+
+		return
+	}
+
+	var body struct {
+		Label *string `json:"label"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "Invalid request body")
+
+		return
+	}
+
+	log.Printf("User %s updating label for address ID: %d", userID, addressID)
+
+	addr, err := h.addresses.UpdateLabel(r.Context(), addressID, userID, body.Label)
+	if err != nil {
+		log.Printf("Error updating address label: %v", err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to update address")
+
+		return
+	}
+
+	if addr == nil {
+		writeError(w, http.StatusNotFound, "NOT_FOUND", "Address not found")
+
+		return
+	}
+
+	writeJSON(w, http.StatusOK, addr)
+}
+
 // Remove handles DELETE requests to remove a tracked address.
 func (h *AddressHandler) Remove(w http.ResponseWriter, r *http.Request) {
 	userID := middleware.GetUserID(r.Context())

backend/internal/handlers/alert_event.go

@@ -4,11 +4,10 @@ import (
 	"log"
 	"net/http"
 	"strconv"
-	"time"
 
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
-	"github.com/kjannette/koin-ping/backend-go/internal/middleware"
-	"github.com/kjannette/koin-ping/backend-go/internal/models"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/middleware"
+	"github.com/kjannette/koin-ping/backend/internal/models"
 )
 
 // AlertEventHandler handles HTTP requests for alert event history.
@@ -51,45 +50,9 @@ func (h *AlertEventHandler) List(w http.ResponseWriter, r *http.Request) {
 
 	log.Printf("Found %d alert events for user", len(events))
 
-	// MVP scaffolding: return mock data if DB is empty
-	if len(events) == 0 {
-		events = mockEvents(limit)
+	if events == nil {
+		events = []domain.AlertEvent{}
 	}
 
 	writeJSON(w, http.StatusOK, events)
 }
-
-func mockEvents(limit int) []domain.AlertEvent {
-	label1 := "Treasury Wallet"
-	label2 := "Cold Storage"
-
-	mocks := []domain.AlertEvent{
-		{
-			ID:           1,
-			AlertRuleID:  1,
-			Message:      "Incoming transaction detected: 5.5 ETH received",
-			AddressLabel: &label1,
-			Timestamp:    time.Now().Add(-2 * time.Hour),
-		},
-		{
-			ID:           2,           //nolint:mnd
-			AlertRuleID:  2,           //nolint:mnd
-			Message:      "Balance dropped below threshold: Current balance 8.2 ETH",
-			AddressLabel: &label1,
-			Timestamp:    time.Now().Add(-5 * time.Hour),
-		},
-		{
-			ID:           3,           //nolint:mnd
-			AlertRuleID:  3,           //nolint:mnd
-			Message:      "Outgoing transaction detected: 2.0 ETH sent",
-			AddressLabel: &label2,
-			Timestamp:    time.Now().Add(-24 * time.Hour),
-		},
-	}
-
-	if limit < len(mocks) {
-		return mocks[:limit]
-	}
-
-	return mocks
-}

backend/internal/handlers/alert_rule.go

@@ -9,26 +9,23 @@ import (
 	"strconv"
 	"strings"
 
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
-	"github.com/kjannette/koin-ping/backend-go/internal/middleware"
-	"github.com/kjannette/koin-ping/backend-go/internal/models"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/middleware"
+	"github.com/kjannette/koin-ping/backend/internal/models"
 )
 
-// errThresholdFormat is returned when the threshold JSON cannot be decoded.
 var errThresholdFormat = errors.New("unsupported threshold format")
 
-// AlertRuleHandler handles HTTP requests for alert rule management.
 type AlertRuleHandler struct {
 	alertRules *models.AlertRuleModel
 	addresses  *models.AddressModel
+	users      *models.UserModel
 }
 
-// NewAlertRuleHandler creates a new AlertRuleHandler.
-func NewAlertRuleHandler(alertRules *models.AlertRuleModel, addresses *models.AddressModel) *AlertRuleHandler {
-	return &AlertRuleHandler{alertRules: alertRules, addresses: addresses}
+func NewAlertRuleHandler(alertRules *models.AlertRuleModel, addresses *models.AddressModel, users *models.UserModel) *AlertRuleHandler {
+	return &AlertRuleHandler{alertRules: alertRules, addresses: addresses, users: users}
 }
 
-// Create handles POST requests to create a new alert rule for an address.
 func (h *AlertRuleHandler) Create(w http.ResponseWriter, r *http.Request) {
 	userID := middleware.GetUserID(r.Context())
 	addressID, ok := parseIntParam(r.PathValue("addressId"))
@@ -41,6 +38,8 @@ func (h *AlertRuleHandler) Create(w http.ResponseWriter, r *http.Request) {
 	var body struct {
 		Type      string          `json:"type"`
 		Threshold json.RawMessage `json:"threshold"`
+		Minimum   json.RawMessage `json:"minimum"`
+		Maximum   json.RawMessage `json:"maximum"`
 	}
 	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
 		log.Printf("Failed to decode alert request body: %v", err)
@@ -57,6 +56,40 @@ func (h *AlertRuleHandler) Create(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	minimum, err := parseThreshold(body.Minimum)
+	if err != nil {
+		log.Printf("Failed to parse minimum: %v", err)
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "minimum must be a valid number")
+
+		return
+	}
+
+	maximum, err := parseThreshold(body.Maximum)
+	if err != nil {
+		log.Printf("Failed to parse maximum: %v", err)
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "maximum must be a valid number")
+
+		return
+	}
+
+	if minimum != nil && *minimum < 0 {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "minimum must be non-negative")
+
+		return
+	}
+
+	if maximum != nil && *maximum < 0 {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "maximum must be non-negative")
+
+		return
+	}
+
+	if minimum != nil && maximum != nil && *minimum > *maximum {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "minimum must not exceed maximum")
+
+		return
+	}
+
 	log.Printf("User %s creating alert: type=%s, addressID=%d", userID, body.Type, addressID)
 
 	if body.Type == "" {
@@ -100,7 +133,29 @@ func (h *AlertRuleHandler) Create(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	newAlert, err := h.alertRules.Create(r.Context(), addressID, alertType, threshold)
+	user, userErr := h.users.GetByID(r.Context(), userID)
+	if userErr != nil || user == nil {
+		log.Printf("Failed to get user %s for tier check: %v", userID, userErr)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to verify account")
+		return
+	}
+
+	limits := domain.GetTierLimits(user.SubscriptionTier)
+	if !limits.IsUnlimitedAlertTypes() {
+		typeCount, countErr := h.alertRules.CountDistinctTypesByAddress(r.Context(), addressID)
+		if countErr != nil {
+			log.Printf("Failed to count alert types for address %d: %v", addressID, countErr)
+			writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to create alert rule")
+			return
+		}
+		if typeCount >= limits.MaxAlertTypes {
+			writeError(w, http.StatusForbidden, "TIER_LIMIT_REACHED",
+				fmt.Sprintf("Your %s plan allows %d alert type(s) per address. Upgrade for more.", user.SubscriptionTier, limits.MaxAlertTypes))
+			return
+		}
+	}
+
+	newAlert, err := h.alertRules.Create(r.Context(), addressID, alertType, threshold, minimum, maximum)
 	if err != nil {
 		log.Printf("Error creating alert rule: %v", err)
 		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to create alert rule")
@@ -186,7 +241,7 @@ func (h *AlertRuleHandler) ListByAddress(w http.ResponseWriter, r *http.Request)
 	writeJSON(w, http.StatusOK, alerts)
 }
 
-// UpdateStatus handles PATCH requests to enable or disable an alert rule.
+// UpdateStatus handles PATCH requests to enable/disable an alert rule and/or update min/max thresholds.
 func (h *AlertRuleHandler) UpdateStatus(w http.ResponseWriter, r *http.Request) {
 	userID := middleware.GetUserID(r.Context())
 	alertID, ok := parseIntParam(r.PathValue("alertId"))
@@ -198,6 +253,9 @@ func (h *AlertRuleHandler) UpdateStatus(w http.ResponseWriter, r *http.Request)
 
 	var body struct {
 		Enabled        *bool           `json:"enabled"`
+		Minimum        json.RawMessage `json:"minimum"`
+		Maximum        json.RawMessage `json:"maximum"`
+		UpdateMinMax   bool            `json:"update_min_max"`   //nolint:tagliatelle
 	}
 	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
 		log.Printf("Failed to decode update request body: %v", err)
@@ -208,8 +266,8 @@ func (h *AlertRuleHandler) UpdateStatus(w http.ResponseWriter, r *http.Request)
 
 	log.Printf("User %s updating alert ID: %d", userID, alertID)
 
-	if body.Enabled == nil {
-		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "enabled must be a boolean value")
+	if body.Enabled == nil && !body.UpdateMinMax {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "must provide enabled (boolean) or update_min_max with minimum/maximum values")
 
 		return
 	}
@@ -228,7 +286,54 @@ func (h *AlertRuleHandler) UpdateStatus(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
-	updated, err := h.alertRules.UpdateEnabled(r.Context(), alertID, *body.Enabled)
+	var updated *domain.AlertRule
+
+	if body.UpdateMinMax {
+		minimum, parseErr := parseThreshold(body.Minimum)
+		if parseErr != nil {
+			writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "minimum must be a valid number")
+
+			return
+		}
+
+		maximum, parseErr := parseThreshold(body.Maximum)
+		if parseErr != nil {
+			writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "maximum must be a valid number")
+
+			return
+		}
+
+		if minimum != nil && *minimum < 0 {
+			writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "minimum must be non-negative")
+
+			return
+		}
+
+		if maximum != nil && *maximum < 0 {
+			writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "maximum must be non-negative")
+
+			return
+		}
+
+		if minimum != nil && maximum != nil && *minimum > *maximum {
+			writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "minimum must not exceed maximum")
+
+			return
+		}
+
+		updated, err = h.alertRules.UpdateThresholds(r.Context(), alertID, minimum, maximum)
+		if err != nil {
+			log.Printf("Error updating alert thresholds: %v", err)
+			writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to update alert")
+
+			return
+		}
+
+		log.Printf("Alert %d thresholds updated: min=%v, max=%v", alertID, minimum, maximum)
+	}
+
+	if body.Enabled != nil {
+		updated, err = h.alertRules.UpdateEnabled(r.Context(), alertID, *body.Enabled)
 		if err != nil {
 			log.Printf("Error updating alert: %v", err)
 			writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to update alert")
@@ -237,6 +342,8 @@ func (h *AlertRuleHandler) UpdateStatus(w http.ResponseWriter, r *http.Request)
 		}
 
 		log.Printf("Alert %d updated: enabled=%v", alertID, *body.Enabled)
+	}
+
 	writeJSON(w, http.StatusOK, updated)
 }
 

backend/internal/handlers/email_digest.go

@@ -0,0 +1,101 @@
+package handlers
+
+import (
+	"log"
+	"net/http"
+
+	"github.com/kjannette/koin-ping/backend/internal/middleware"
+	"github.com/kjannette/koin-ping/backend/internal/models"
+	"github.com/kjannette/koin-ping/backend/internal/services"
+)
+
+type EmailDigestHandler struct {
+	digestSvc *services.EmailDigestService
+	configs   *models.NotificationConfigModel
+}
+
+func NewEmailDigestHandler(
+	digestSvc *services.EmailDigestService,
+	configs *models.NotificationConfigModel,
+) *EmailDigestHandler {
+	return &EmailDigestHandler{digestSvc: digestSvc, configs: configs}
+}
+
+// SetupEmail reads the user's email from their notification config and sends
+// a confirmation message via Resend to verify the integration works.
+func (h *EmailDigestHandler) SetupEmail(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+
+	if !h.digestSvc.Configured() {
+		writeError(w, http.StatusServiceUnavailable, "EMAIL_NOT_CONFIGURED",
+			"Email service is not configured on the server")
+		return
+	}
+
+	cfg, err := h.configs.GetConfig(r.Context(), userID)
+	if err != nil {
+		log.Printf("Error getting notification config for email setup: %v", err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR",
+			"Failed to load notification config")
+		return
+	}
+
+	if cfg == nil || cfg.Email == nil || *cfg.Email == "" {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR",
+			"Save an email address in notification settings first")
+		return
+	}
+
+	if err := h.digestSvc.SetupEmail(*cfg.Email); err != nil {
+		log.Printf("Email setup failed for user %s: %v", userID, err)
+		writeError(w, http.StatusBadGateway, "EMAIL_SEND_FAILED",
+			"Failed to send confirmation email — check server email config")
+		return
+	}
+
+	log.Printf("Email setup confirmation sent to user %s (%s)", userID, *cfg.Email)
+	writeJSON(w, http.StatusOK, map[string]any{
+		"success": true,
+		"email":   *cfg.Email,
+		"message": "Confirmation email sent",
+	})
+}
+
+// SendDigest compiles and sends a digest of recent alerts to the user's email.
+func (h *EmailDigestHandler) SendDigest(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+
+	if !h.digestSvc.Configured() {
+		writeError(w, http.StatusServiceUnavailable, "EMAIL_NOT_CONFIGURED",
+			"Email service is not configured on the server")
+		return
+	}
+
+	cfg, err := h.configs.GetConfig(r.Context(), userID)
+	if err != nil {
+		log.Printf("Error getting notification config for digest: %v", err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR",
+			"Failed to load notification config")
+		return
+	}
+
+	if cfg == nil || cfg.Email == nil || *cfg.Email == "" {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR",
+			"No email address configured")
+		return
+	}
+
+	if err := h.digestSvc.SendDigest(r.Context(), userID, *cfg.Email); err != nil {
+		log.Printf("Digest send failed for user %s: %v", userID, err)
+		writeError(w, http.StatusBadGateway, "DIGEST_SEND_FAILED",
+			"Failed to send digest email")
+		return
+	}
+
+	log.Printf("Digest sent to user %s (%s)", userID, *cfg.Email)
+	writeJSON(w, http.StatusOK, map[string]any{
+		"success": true,
+		"email":   *cfg.Email,
+		"message": "Digest email sent",
+	})
+}

backend/internal/handlers/notification_config.go

@@ -0,0 +1,237 @@
+package handlers
+
+import (
+	"encoding/json"
+	"log"
+	"net/http"
+	"regexp"
+	"strings"
+
+	"github.com/kjannette/koin-ping/backend/internal/config"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/middleware"
+	"github.com/kjannette/koin-ping/backend/internal/models"
+	"github.com/kjannette/koin-ping/backend/internal/notifications"
+)
+
+var emailRe = regexp.MustCompile(`^[^\s@]+@[^\s@]+\.[^\s@]+$`)
+
+type NotificationConfigHandler struct {
+	configs *models.NotificationConfigModel
+	users   *models.UserModel
+	cfg     *config.Config
+}
+
+func NewNotificationConfigHandler(configs *models.NotificationConfigModel, users *models.UserModel, cfg *config.Config) *NotificationConfigHandler {
+	return &NotificationConfigHandler{configs: configs, users: users, cfg: cfg}
+}
+
+func (h *NotificationConfigHandler) GetConfig(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+	log.Printf("User %s getting notification config", userID)
+
+	cfg, err := h.configs.GetConfig(r.Context(), userID)
+	if err != nil {
+		log.Printf("Error getting notification config: %v", err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to get notification config")
+		return
+	}
+
+	if cfg == nil {
+		writeJSON(w, http.StatusOK, domain.NotificationConfig{
+			UserID:              userID,
+			NotificationEnabled: true,
+		})
+		return
+	}
+
+	log.Println("Config found")
+	writeJSON(w, http.StatusOK, cfg)
+}
+
+func (h *NotificationConfigHandler) UpdateConfig(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+
+	var body struct {
+		DiscordWebhookURL   *string `json:"discord_webhook_url"`
+		TelegramChatID      *string `json:"telegram_chat_id"`
+		TelegramBotToken    *string `json:"telegram_bot_token"`
+		Email               *string `json:"email"`
+		SlackWebhookURL     *string `json:"slack_webhook_url"`
+		NotificationEnabled *bool   `json:"notification_enabled"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		log.Printf("Failed to decode notification config request body: %v", err)
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "Invalid request body")
+		return
+	}
+
+	log.Printf("User %s updating notification config", userID)
+
+	if body.DiscordWebhookURL == nil && body.TelegramChatID == nil &&
+		body.TelegramBotToken == nil && body.Email == nil &&
+		body.SlackWebhookURL == nil && body.NotificationEnabled == nil {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR",
+			"At least one configuration field must be provided")
+		return
+	}
+
+	if body.DiscordWebhookURL != nil && *body.DiscordWebhookURL != "" &&
+		!strings.HasPrefix(*body.DiscordWebhookURL, "https://discord.com/api/webhooks/") {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR",
+			"Invalid Discord webhook URL format")
+		return
+	}
+
+	if body.SlackWebhookURL != nil && *body.SlackWebhookURL != "" &&
+		!strings.HasPrefix(*body.SlackWebhookURL, "https://hooks.slack.com/") {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR",
+			"Invalid Slack webhook URL format")
+		return
+	}
+
+	if body.Email != nil && *body.Email != "" && !emailRe.MatchString(*body.Email) {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR",
+			"Invalid email address format")
+		return
+	}
+
+	user, userErr := h.users.GetByID(r.Context(), userID)
+	if userErr != nil || user == nil {
+		log.Printf("Failed to get user %s for tier check: %v", userID, userErr)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to verify account")
+		return
+	}
+
+	limits := domain.GetTierLimits(user.SubscriptionTier)
+
+	if !limits.ChannelAllowed("discord") {
+		body.DiscordWebhookURL = nil
+	}
+	if !limits.ChannelAllowed("telegram") {
+		body.TelegramBotToken = nil
+		body.TelegramChatID = nil
+	}
+	if !limits.ChannelAllowed("slack") {
+		body.SlackWebhookURL = nil
+	}
+
+	enabled := true
+	if body.NotificationEnabled != nil {
+		enabled = *body.NotificationEnabled
+	}
+
+	cfg := domain.NotificationConfig{
+		DiscordWebhookURL:   body.DiscordWebhookURL,
+		TelegramChatID:      body.TelegramChatID,
+		TelegramBotToken:    body.TelegramBotToken,
+		Email:               body.Email,
+		SlackWebhookURL:     body.SlackWebhookURL,
+		NotificationEnabled: enabled,
+	}
+
+	updated, err := h.configs.UpsertConfig(r.Context(), userID, cfg)
+	if err != nil {
+		log.Printf("Error updating notification config: %v", err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR",
+			"Failed to update notification configuration")
+		return
+	}
+
+	log.Println("Notification config updated")
+	writeJSON(w, http.StatusOK, updated)
+}
+
+func (h *NotificationConfigHandler) DeleteConfig(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+	log.Printf("User %s deleting notification config", userID)
+
+	deleted, err := h.configs.Remove(r.Context(), userID)
+	if err != nil {
+		log.Printf("Error deleting notification config: %v", err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR",
+			"Failed to delete notification configuration")
+		return
+	}
+
+	if !deleted {
+		writeError(w, http.StatusNotFound, "NOT_FOUND", "No notification configuration found")
+		return
+	}
+
+	log.Println("Notification config deleted")
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// TestChannels sends a test message to all configured notification channels.
+func (h *NotificationConfigHandler) TestChannels(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+	log.Printf("User %s testing notification channels", userID)
+
+	cfg, err := h.configs.GetConfig(r.Context(), userID)
+	if err != nil {
+		log.Printf("Error getting notification config for test: %v", err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to get notification config")
+		return
+	}
+
+	if cfg == nil {
+		writeError(w, http.StatusNotFound, "NOT_FOUND", "No notification configuration found")
+		return
+	}
+
+	type channelResult struct {
+		Channel string `json:"channel"`
+		Success bool   `json:"success"`
+		Error   string `json:"error,omitempty"`
+	}
+
+	var results []channelResult
+
+	if cfg.DiscordWebhookURL != nil && *cfg.DiscordWebhookURL != "" {
+		ok, testErr := notifications.TestDiscordWebhook(*cfg.DiscordWebhookURL)
+		res := channelResult{Channel: "discord", Success: ok}
+		if testErr != nil {
+			res.Error = testErr.Error()
+		}
+		results = append(results, res)
+	}
+
+	if cfg.TelegramBotToken != nil && *cfg.TelegramBotToken != "" &&
+		cfg.TelegramChatID != nil && *cfg.TelegramChatID != "" {
+		ok, testErr := notifications.TestTelegramWebhook(*cfg.TelegramBotToken, *cfg.TelegramChatID)
+		res := channelResult{Channel: "telegram", Success: ok}
+		if testErr != nil {
+			res.Error = testErr.Error()
+		}
+		results = append(results, res)
+	}
+
+	if cfg.SlackWebhookURL != nil && *cfg.SlackWebhookURL != "" {
+		ok, testErr := notifications.TestSlackWebhook(*cfg.SlackWebhookURL)
+		res := channelResult{Channel: "slack", Success: ok}
+		if testErr != nil {
+			res.Error = testErr.Error()
+		}
+		results = append(results, res)
+	}
+
+	if cfg.Email != nil && *cfg.Email != "" {
+		ok, testErr := notifications.TestEmailNotification(
+			h.cfg.ResendAPIKey, h.cfg.EmailFrom, *cfg.Email,
+		)
+		res := channelResult{Channel: "email", Success: ok}
+		if testErr != nil {
+			res.Error = testErr.Error()
+		}
+		results = append(results, res)
+	}
+
+	if len(results) == 0 {
+		writeError(w, http.StatusBadRequest, "NO_CHANNELS",
+			"No notification channels are configured")
+		return
+	}
+
+	writeJSON(w, http.StatusOK, map[string]any{"results": results})
+}

backend/internal/handlers/status.go

@@ -0,0 +1,71 @@
+package handlers
+
+import (
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/kjannette/koin-ping/backend/internal/models"
+)
+
+// StatusHandler handles the system status endpoint.
+type StatusHandler struct {
+	checkpoints *models.CheckpointModel
+}
+
+// NewStatusHandler creates a new StatusHandler.
+func NewStatusHandler(checkpoints *models.CheckpointModel) *StatusHandler {
+	return &StatusHandler{checkpoints: checkpoints}
+}
+
+// GetStatus returns real-time system status derived from checkpoint data.
+func (h *StatusHandler) GetStatus(w http.ResponseWriter, r *http.Request) {
+	block, checkedAt, err := h.checkpoints.GetLatestBlock(r.Context())
+	if err != nil {
+		log.Printf("Error querying latest block: %v", err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to get system status")
+
+		return
+	}
+
+	latestBlock := 0
+	lag := 0
+	status := "starting"
+
+	if checkedAt != nil {
+		lag = int(time.Since(*checkedAt).Seconds())
+		if lag > 600 { //nolint:mnd
+			status = "idle"
+		} else {
+			status = "active"
+		}
+	}
+
+	if block != nil {
+		latestBlock = *block
+	}
+
+	writeJSON(w, http.StatusOK, map[string]interface{}{
+		"status":        status,
+		"latestBlock":   latestBlock,
+		"lag":           lag,
+		"lastCheckedAt": checkedAtStr(checkedAt),
+		"timestamp":     time.Now().UTC().Format(time.RFC3339),
+	})
+}
+
+func checkedAtStr(t *time.Time) string {
+	if t == nil {
+		return ""
+	}
+
+	return t.UTC().Format(time.RFC3339)
+}
+
+func HealthCheck(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, map[string]interface{}{
+		"status":    "ok",
+		"timestamp": time.Now().UTC().Format(time.RFC3339),
+		"service":   "koin-ping-backend",
+	})
+}

backend/internal/handlers/stripe.go

@@ -0,0 +1,497 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+
+	kpfirebase "github.com/kjannette/koin-ping/backend/internal/firebase"
+	"github.com/kjannette/koin-ping/backend/internal/config"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/middleware"
+	"github.com/kjannette/koin-ping/backend/internal/models"
+	"github.com/stripe/stripe-go/v82"
+	portalsession "github.com/stripe/stripe-go/v82/billingportal/session"
+	checkoutsession "github.com/stripe/stripe-go/v82/checkout/session"
+	"github.com/stripe/stripe-go/v82/webhook"
+)
+
+const webhookMaxBodyBytes = 65536
+
+type StripeHandler struct {
+	users  *models.UserModel
+	alerts *models.AlertRuleModel
+	cfg    *config.Config
+}
+
+func NewStripeHandler(users *models.UserModel, alerts *models.AlertRuleModel, cfg *config.Config) *StripeHandler {
+	stripe.Key = cfg.StripeSecretKey
+	return &StripeHandler{users: users, alerts: alerts, cfg: cfg}
+}
+
+func (h *StripeHandler) ensureUserFirebaseAndAlertsEnabled(ctx context.Context, localUserID string) {
+	user, err := h.users.GetByID(ctx, localUserID)
+	if err != nil || user == nil || user.FirebaseUID == "" {
+		return
+	}
+	if firebaseErr := kpfirebase.SetUserDisabled(ctx, user.FirebaseUID, false); firebaseErr != nil {
+		log.Printf("Billing access restore: firebase enable failed for user %s: %v", localUserID, firebaseErr)
+
+		return
+	}
+
+	n, alertsErr := h.alerts.EnableAllForUser(ctx, localUserID)
+	if alertsErr != nil {
+		log.Printf("Billing access restore: enable alerts failed for user %s: %v", localUserID, alertsErr)
+
+		return
+	}
+
+	log.Printf("Billing access restored: user %s, %d alert rules enabled", localUserID, n)
+}
+
+func (h *StripeHandler) restorePaidSubscriptionAccess(ctx context.Context, stripeCustomerID, status string) {
+	if stripeCustomerID == "" || (status != "active" && status != "trialing") {
+		return
+	}
+
+	u, err := h.users.GetByStripeCustomerID(ctx, stripeCustomerID)
+	if err != nil || u == nil {
+		if err != nil {
+			log.Printf("restorePaidSubscriptionAccess: lookup %s: %v", stripeCustomerID, err)
+		}
+
+		return
+	}
+
+	h.ensureUserFirebaseAndAlertsEnabled(ctx, u.ID)
+}
+
+func (h *StripeHandler) priceIDForTier(tier domain.SubscriptionTier, interval string) (string, error) {
+	if interval == "annual" {
+		switch tier {
+		case domain.TierPremium:
+			return h.cfg.StripePriceIDPremiumAnnual, nil
+		case domain.TierPro:
+			return h.cfg.StripePriceIDProAnnual, nil
+		default:
+			return "", fmt.Errorf("no Stripe price for tier %q", tier) //nolint:err113
+		}
+	}
+	switch tier {
+	case domain.TierPremium:
+		return h.cfg.StripePriceIDPremium, nil
+	case domain.TierPro:
+		return h.cfg.StripePriceIDPro, nil
+	default:
+		return "", fmt.Errorf("no Stripe price for tier %q", tier) //nolint:err113
+	}
+}
+
+// CreateCheckoutSession creates a Stripe Checkout session for the selected tier.
+func (h *StripeHandler) CreateCheckoutSession(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+
+	var body struct {
+		Tier     string `json:"tier"`
+		Interval string `json:"interval"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, http.StatusBadRequest, "BAD_REQUEST", "Invalid request body")
+		return
+	}
+
+	if body.Tier == "" {
+		body.Tier = "premium"
+	}
+	if body.Interval == "" {
+		body.Interval = "annual"
+	}
+
+	tier := domain.SubscriptionTier(body.Tier)
+	if tier != domain.TierPremium && tier != domain.TierPro {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "Tier must be 'premium' or 'pro'")
+		return
+	}
+
+	priceID, err := h.priceIDForTier(tier, body.Interval)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", err.Error())
+		return
+	}
+
+	user, err := h.users.GetByID(r.Context(), userID)
+	if err != nil || user == nil {
+		log.Printf("Failed to get user %s: %v", userID, err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to load user")
+		return
+	}
+
+	params := &stripe.CheckoutSessionParams{
+		Mode: stripe.String(string(stripe.CheckoutSessionModeSubscription)),
+		LineItems: []*stripe.CheckoutSessionLineItemParams{
+			{
+				Price:    stripe.String(priceID),
+				Quantity: stripe.Int64(1),
+			},
+		},
+		SuccessURL:        stripe.String(h.cfg.FrontendURL + "/subscribe/return/{CHECKOUT_SESSION_ID}"),
+		CancelURL:         stripe.String(h.cfg.FrontendURL + "/subscribe?payment=cancelled"),
+		ClientReferenceID: stripe.String(userID),
+		CustomerEmail:     stripe.String(user.Email),
+	}
+
+	params.AddMetadata("tier", string(tier))
+
+	if user.StripeCustomerID != nil && *user.StripeCustomerID != "" {
+		params.Customer = user.StripeCustomerID
+		params.CustomerEmail = nil
+	}
+
+	s, err := checkoutsession.New(params)
+	if err != nil {
+		log.Printf("Failed to create Stripe checkout session: %v", err)
+		writeError(w, http.StatusInternalServerError, "STRIPE_ERROR", "Failed to create checkout session")
+		return
+	}
+
+	writeJSON(w, http.StatusOK, map[string]string{"url": s.URL})
+}
+
+// GetSubscriptionStatus returns the current user's subscription state.
+func (h *StripeHandler) GetSubscriptionStatus(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+
+	user, err := h.users.GetByID(r.Context(), userID)
+	if err != nil || user == nil {
+		log.Printf("Failed to get user %s: %v", userID, err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to load user")
+		return
+	}
+
+	writeJSON(w, http.StatusOK, map[string]any{
+		"subscription_status": user.SubscriptionStatus,
+		"subscription_tier":   user.SubscriptionTier,
+		"subscription_created_at": user.SubscriptionCreatedAt,
+	})
+}
+
+// VerifyCheckoutSession retrieves a completed checkout session from Stripe,
+// confirms payment, and activates the user's subscription in the database.
+func (h *StripeHandler) VerifyCheckoutSession(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+
+	var body struct {
+		SessionID string `json:"session_id"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil || body.SessionID == "" {
+		writeError(w, http.StatusBadRequest, "BAD_REQUEST", "Missing session_id")
+		return
+	}
+
+	s, err := checkoutsession.Get(body.SessionID, nil)
+	if err != nil {
+		log.Printf("Failed to retrieve checkout session %s: %v", body.SessionID, err)
+		writeError(w, http.StatusBadRequest, "STRIPE_ERROR", "Invalid checkout session")
+		return
+	}
+
+	if s.ClientReferenceID != "" && s.ClientReferenceID != userID {
+		writeError(w, http.StatusForbidden, "FORBIDDEN", "Session does not belong to this user")
+		return
+	}
+
+	if s.PaymentStatus != stripe.CheckoutSessionPaymentStatusPaid {
+		writeError(w, http.StatusBadRequest, "PAYMENT_INCOMPLETE", "Payment has not been completed")
+		return
+	}
+
+	tier := domain.TierPremium
+	if t, ok := s.Metadata["tier"]; ok && domain.IsValidTier(t) {
+		tier = domain.SubscriptionTier(t)
+	}
+
+	customerID := ""
+	if s.Customer != nil {
+		customerID = s.Customer.ID
+	}
+	subscriptionID := ""
+	if s.Subscription != nil {
+		subscriptionID = s.Subscription.ID
+	}
+
+	if customerID != "" {
+		if err := h.users.UpdateStripeCustomer(r.Context(), userID, customerID); err != nil {
+			log.Printf("VerifyCheckout: failed to save customer ID: %v", err)
+		}
+	}
+	if subscriptionID != "" && customerID != "" {
+		if err := h.users.ActivateSubscription(r.Context(), customerID, subscriptionID, "active", tier); err != nil {
+			log.Printf("VerifyCheckout: failed to activate subscription: %v", err)
+		} else {
+			h.restorePaidSubscriptionAccess(r.Context(), customerID, "active")
+		}
+	}
+
+	log.Printf("Checkout verified for user %s, customer %s, subscription %s, tier %s", userID, customerID, subscriptionID, tier)
+	writeJSON(w, http.StatusOK, map[string]string{
+		"subscription_status": "active",
+		"subscription_tier":   string(tier),
+	})
+}
+
+// ActivateFreeTier sets the user to the free tier without Stripe involvement.
+func (h *StripeHandler) ActivateFreeTier(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+
+	if err := h.users.ActivateFreeTier(r.Context(), userID); err != nil {
+		log.Printf("ActivateFreeTier: failed for user %s: %v", userID, err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to activate free tier")
+		return
+	}
+
+	h.ensureUserFirebaseAndAlertsEnabled(r.Context(), userID)
+
+	log.Printf("Free tier activated for user %s", userID)
+	writeJSON(w, http.StatusOK, map[string]string{
+		"subscription_status": "active",
+		"subscription_tier":   "free",
+	})
+}
+
+// CreateOnboardingCheckout creates a Stripe Checkout session for a user who
+// has not yet created an account. This is a public endpoint (no auth required).
+// The Firebase account is created on the frontend only after payment succeeds.
+func (h *StripeHandler) CreateOnboardingCheckout(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		Email    string `json:"email"`
+		Tier     string `json:"tier"`
+		Interval string `json:"interval"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, http.StatusBadRequest, "BAD_REQUEST", "Invalid request body")
+		return
+	}
+
+	if body.Email == "" {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "Email is required")
+		return
+	}
+
+	if body.Tier == "" {
+		body.Tier = "premium"
+	}
+	if body.Interval == "" {
+		body.Interval = "annual"
+	}
+
+	tier := domain.SubscriptionTier(body.Tier)
+	if tier != domain.TierPremium && tier != domain.TierPro {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", "Tier must be 'premium' or 'pro'")
+		return
+	}
+
+	priceID, err := h.priceIDForTier(tier, body.Interval)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, "VALIDATION_ERROR", err.Error())
+		return
+	}
+
+	params := &stripe.CheckoutSessionParams{
+		Mode: stripe.String(string(stripe.CheckoutSessionModeSubscription)),
+		LineItems: []*stripe.CheckoutSessionLineItemParams{
+			{
+				Price:    stripe.String(priceID),
+				Quantity: stripe.Int64(1),
+			},
+		},
+		SuccessURL:    stripe.String(h.cfg.FrontendURL + "/subscribe/return/{CHECKOUT_SESSION_ID}"),
+		CancelURL:     stripe.String(h.cfg.FrontendURL + "/subscribe?payment=cancelled"),
+		CustomerEmail: stripe.String(body.Email),
+	}
+	params.AddMetadata("tier", string(tier))
+	params.AddMetadata("onboarding", "true")
+
+	s, err := checkoutsession.New(params)
+	if err != nil {
+		log.Printf("Failed to create onboarding checkout session: %v", err)
+		writeError(w, http.StatusInternalServerError, "STRIPE_ERROR", "Failed to create checkout session")
+		return
+	}
+
+	writeJSON(w, http.StatusOK, map[string]string{"url": s.URL})
+}
+
+// CreatePortalSession creates a Stripe Billing Portal session so the user can
+// manage their subscription (cancel, update payment method, view invoices).
+func (h *StripeHandler) CreatePortalSession(w http.ResponseWriter, r *http.Request) {
+	userID := middleware.GetUserID(r.Context())
+
+	user, err := h.users.GetByID(r.Context(), userID)
+	if err != nil || user == nil {
+		log.Printf("Portal: failed to get user %s: %v", userID, err)
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to load user")
+		return
+	}
+
+	if user.StripeCustomerID == nil || *user.StripeCustomerID == "" {
+		writeError(w, http.StatusBadRequest, "NO_CUSTOMER", "No Stripe customer on file")
+		return
+	}
+
+	params := &stripe.BillingPortalSessionParams{
+		Customer:  user.StripeCustomerID,
+		ReturnURL: stripe.String(h.cfg.FrontendURL + "/account"),
+	}
+
+	s, err := portalsession.New(params)
+	if err != nil {
+		log.Printf("Portal: failed to create portal session: %v", err)
+		writeError(w, http.StatusInternalServerError, "STRIPE_ERROR", "Failed to create portal session")
+		return
+	}
+
+	writeJSON(w, http.StatusOK, map[string]string{"url": s.URL})
+}
+
+// HandleWebhook processes incoming Stripe webhook events.
+func (h *StripeHandler) HandleWebhook(w http.ResponseWriter, r *http.Request) {
+	payload, err := io.ReadAll(io.LimitReader(r.Body, webhookMaxBodyBytes))
+	if err != nil {
+		log.Printf("Error reading webhook body: %v", err)
+		w.WriteHeader(http.StatusServiceUnavailable)
+		return
+	}
+
+	sig := r.Header.Get("Stripe-Signature")
+	event, err := webhook.ConstructEvent(payload, sig, h.cfg.StripeWebhookSecret)
+	if err != nil {
+		log.Printf("Webhook signature verification failed: %v", err)
+		w.WriteHeader(http.StatusBadRequest)
+		return
+	}
+
+	switch event.Type {
+	case "checkout.session.completed":
+		h.handleCheckoutCompleted(r, event)
+	case "customer.subscription.updated":
+		h.handleSubscriptionUpdated(r, event)
+	case "customer.subscription.deleted":
+		h.handleSubscriptionDeleted(r, event)
+	default:
+		log.Printf("Unhandled Stripe event type: %s", event.Type)
+	}
+
+	w.WriteHeader(http.StatusOK)
+}
+
+func (h *StripeHandler) handleCheckoutCompleted(r *http.Request, event stripe.Event) {
+	var session stripe.CheckoutSession
+	if err := json.Unmarshal(event.Data.Raw, &session); err != nil {
+		log.Printf("Error parsing checkout session: %v", err)
+		return
+	}
+
+	userID := session.ClientReferenceID
+	if userID == "" {
+		log.Println("Checkout session missing client_reference_id")
+		return
+	}
+
+	tier := domain.TierPremium
+	if t, ok := session.Metadata["tier"]; ok && domain.IsValidTier(t) {
+		tier = domain.SubscriptionTier(t)
+	}
+
+	customerID := ""
+	if session.Customer != nil {
+		customerID = session.Customer.ID
+	}
+	subscriptionID := ""
+	if session.Subscription != nil {
+		subscriptionID = session.Subscription.ID
+	}
+
+	if customerID != "" {
+		if err := h.users.UpdateStripeCustomer(r.Context(), userID, customerID); err != nil {
+			log.Printf("Failed to save Stripe customer ID: %v", err)
+		}
+	}
+
+	if subscriptionID != "" && customerID != "" {
+		if err := h.users.ActivateSubscription(r.Context(), customerID, subscriptionID, "active", tier); err != nil {
+			log.Printf("Failed to activate subscription: %v", err)
+		} else {
+			h.restorePaidSubscriptionAccess(r.Context(), customerID, "active")
+		}
+	}
+
+	log.Printf("Checkout completed for user %s, customer %s, subscription %s, tier %s", userID, customerID, subscriptionID, tier)
+}
+
+func (h *StripeHandler) handleSubscriptionUpdated(r *http.Request, event stripe.Event) {
+	var sub stripe.Subscription
+	if err := json.Unmarshal(event.Data.Raw, &sub); err != nil {
+		log.Printf("Error parsing subscription update: %v", err)
+		return
+	}
+
+	customerID := ""
+	if sub.Customer != nil {
+		customerID = sub.Customer.ID
+	}
+	if customerID == "" {
+		return
+	}
+
+	status := string(sub.Status)
+
+	// Detect tier from the subscription's current price so that
+	// upgrades/downgrades via the Stripe portal are reflected.
+	tier := domain.TierPremium
+	if sub.Items != nil {
+		for _, item := range sub.Items.Data {
+			if item.Price != nil {
+				if t := h.cfg.TierForPriceID(item.Price.ID); t != "" {
+					tier = domain.SubscriptionTier(t)
+					break
+				}
+			}
+		}
+	}
+
+	if err := h.users.ActivateSubscription(r.Context(), customerID, sub.ID, status, tier); err != nil {
+		log.Printf("Failed to update subscription: %v", err)
+
+		return
+	}
+
+	h.restorePaidSubscriptionAccess(r.Context(), customerID, status)
+
+	log.Printf("Subscription %s updated to %s (tier %s) for customer %s", sub.ID, status, tier, customerID)
+}
+
+func (h *StripeHandler) handleSubscriptionDeleted(r *http.Request, event stripe.Event) {
+	var sub stripe.Subscription
+	if err := json.Unmarshal(event.Data.Raw, &sub); err != nil {
+		log.Printf("Error parsing subscription deletion: %v", err)
+		return
+	}
+
+	customerID := ""
+	if sub.Customer != nil {
+		customerID = sub.Customer.ID
+	}
+	if customerID == "" {
+		return
+	}
+
+	if err := h.users.UpdateSubscriptionStatus(r.Context(), customerID, "canceled"); err != nil {
+		log.Printf("Failed to mark subscription canceled: %v", err)
+	}
+
+	log.Printf("Subscription canceled for customer %s", customerID)
+}

backend/internal/handlers/support.go

@@ -0,0 +1,111 @@
+package handlers
+
+import (
+	"encoding/json"
+	"log"
+	"net/http"
+	"net/mail"
+	"os"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/kjannette/koin-ping/backend/internal/config"
+	"github.com/kjannette/koin-ping/backend/internal/notifications"
+)
+
+const (
+	maxSupportDescriptionLen = 8000
+	maxSupportEmailLen       = 320
+)
+
+var descriptionAllowedRE = regexp.MustCompile(`^[a-zA-Z0-9\s]+$`)
+
+type supportRequestBody struct {
+	Email       string `json:"email"`
+	Description string `json:"description"`
+}
+
+// SupportHandler accepts authenticated support form submissions and emails the inbox.
+type SupportHandler struct {
+	cfg *config.Config
+}
+
+func NewSupportHandler(cfg *config.Config) *SupportHandler {
+	return &SupportHandler{cfg: cfg}
+}
+
+// Submit handles POST /support.
+func (h *SupportHandler) Submit(w http.ResponseWriter, r *http.Request) {
+	var body supportRequestBody
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, http.StatusBadRequest, "INVALID_JSON", "Request body must be JSON")
+		return
+	}
+
+	email := strings.TrimSpace(body.Email)
+	description := strings.TrimSpace(body.Description)
+
+	if len(email) > maxSupportEmailLen {
+		writeError(w, http.StatusBadRequest, "INVALID_EMAIL", "Email is too long")
+		return
+	}
+
+	parsed, err := mail.ParseAddress(email)
+	if err != nil || parsed.Address == "" {
+		writeError(w, http.StatusBadRequest, "INVALID_EMAIL", "Invalid email address")
+		return
+	}
+
+	canonicalEmail := parsed.Address
+
+	if description == "" {
+		writeError(w, http.StatusBadRequest, "INVALID_DESCRIPTION", "Description is required")
+		return
+	}
+
+	if len(description) > maxSupportDescriptionLen {
+		writeError(w, http.StatusBadRequest, "INVALID_DESCRIPTION", "Description is too long")
+		return
+	}
+
+	if !descriptionAllowedRE.MatchString(description) {
+		writeError(w, http.StatusBadRequest, "INVALID_DESCRIPTION",
+			"Description may only contain letters, numbers, and whitespace")
+		return
+	}
+
+	subject := time.Now().UTC().Format(time.RFC3339) + " - new support issue - koinp.ing"
+	plainBody := "Contact email: " + canonicalEmail + "\n\nIssue description:\n" + description
+
+	// Local dev: skip Resend when SUPPORT_DEV_SKIP_EMAIL=1 (see backend logs for payload).
+	if strings.EqualFold(h.cfg.NodeEnv, "development") && os.Getenv("SUPPORT_DEV_SKIP_EMAIL") == "1" {
+		log.Printf("[dev] SUPPORT_DEV_SKIP_EMAIL: skipping Resend; to=%s subject=%s", h.cfg.SupportInboxEmail, subject)
+		log.Printf("[dev] SUPPORT_DEV_SKIP_EMAIL body:\n%s", plainBody)
+		writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
+		return
+	}
+
+	if h.cfg.ResendAPIKey == "" {
+		writeError(w, http.StatusServiceUnavailable, "EMAIL_UNAVAILABLE", "Support email is not configured")
+		return
+	}
+
+	if err := notifications.SendSupportEmail(
+		h.cfg.ResendAPIKey,
+		h.cfg.EmailFrom,
+		h.cfg.SupportInboxEmail,
+		subject,
+		plainBody,
+	); err != nil {
+		log.Printf("support Submit: send email: %v", err)
+		msg := "Could not send email. Confirm RESEND_API_KEY and that EMAIL_FROM uses a domain verified in Resend."
+		if strings.EqualFold(h.cfg.NodeEnv, "development") {
+			msg = "Email send failed (development): " + err.Error()
+		}
+		writeError(w, http.StatusInternalServerError, "SEND_FAILED", msg)
+		return
+	}
+
+	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
+}

backend/internal/middleware/auth.go

@@ -0,0 +1,161 @@
+// Package middleware provides HTTP middleware for authentication and context injection.
+package middleware
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"net/http"
+	"strings"
+
+	fbauth "github.com/kjannette/koin-ping/backend/internal/firebase"
+	"github.com/kjannette/koin-ping/backend/internal/models"
+)
+
+type contextKey string
+
+const (
+	UserIDKey    contextKey = "user_id"
+	UserEmailKey contextKey = "user_email"
+	UserTierKey  contextKey = "user_tier"
+)
+
+type errorResponse struct {
+	Error   string `json:"error"`
+	Message string `json:"message"`
+}
+
+func writeJSON(w http.ResponseWriter, status int, v interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(v) //nolint:errcheck
+}
+
+// Authenticate verifies the Firebase ID token and auto-provisions a local user
+// record. The local user UUID (not the Firebase UID) is placed into context so
+// all downstream handlers use it as the canonical user identifier.
+func Authenticate(userModel *models.UserModel) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			authHeader := r.Header.Get("Authorization")
+			if authHeader == "" || !strings.HasPrefix(authHeader, "Bearer ") {
+				log.Println("No Authorization header or invalid format")
+				writeJSON(w, http.StatusUnauthorized, errorResponse{
+					Error:   "UNAUTHORIZED",
+					Message: "No authentication token provided",
+				})
+				return
+			}
+
+			token := strings.TrimPrefix(authHeader, "Bearer ")
+			if token == "" {
+				log.Println("Empty token")
+				writeJSON(w, http.StatusUnauthorized, errorResponse{
+					Error:   "UNAUTHORIZED",
+					Message: "Invalid token format",
+				})
+				return
+			}
+
+			log.Println("Verifying Firebase token...")
+			decoded, err := fbauth.Auth().VerifyIDToken(r.Context(), token)
+			if err != nil {
+				log.Printf("Token verification failed: %v", err)
+
+				errMsg := err.Error()
+				if strings.Contains(errMsg, "expired") {
+					writeJSON(w, http.StatusUnauthorized, errorResponse{
+						Error:   "TOKEN_EXPIRED",
+						Message: "Authentication token has expired",
+					})
+					return
+				}
+
+				writeJSON(w, http.StatusUnauthorized, errorResponse{
+					Error:   "UNAUTHORIZED",
+					Message: "Failed to verify authentication token",
+				})
+				return
+			}
+
+			firebaseUID := decoded.UID
+			email, _ := decoded.Claims["email"].(string)
+
+			user, err := userModel.FindOrCreateByFirebaseUID(r.Context(), firebaseUID, email)
+			if err != nil {
+				log.Printf("Failed to provision local user for Firebase UID %s: %v", firebaseUID, err)
+				writeJSON(w, http.StatusInternalServerError, errorResponse{
+					Error:   "INTERNAL_ERROR",
+					Message: "Failed to initialize user account",
+				})
+				return
+			}
+
+			log.Printf("Token verified! User UUID: %s, Email: %s", user.ID, email)
+
+			ctx := context.WithValue(r.Context(), UserIDKey, user.ID)
+			ctx = context.WithValue(ctx, UserEmailKey, email)
+			ctx = context.WithValue(ctx, UserTierKey, string(user.SubscriptionTier))
+
+			next.ServeHTTP(w, r.WithContext(ctx))
+		})
+	}
+}
+
+// RequireSubscription blocks requests from users without an active subscription.
+// Must be applied after Authenticate.
+func RequireSubscription(userModel *models.UserModel) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			userID := GetUserID(r.Context())
+			if userID == "" {
+				writeJSON(w, http.StatusUnauthorized, errorResponse{
+					Error:   "UNAUTHORIZED",
+					Message: "Authentication required",
+				})
+				return
+			}
+
+			user, err := userModel.GetByID(r.Context(), userID)
+			if err != nil || user == nil {
+				log.Printf("RequireSubscription: failed to load user %s: %v", userID, err)
+				writeJSON(w, http.StatusInternalServerError, errorResponse{
+					Error:   "INTERNAL_ERROR",
+					Message: "Failed to verify subscription",
+				})
+				return
+			}
+
+			if user.SubscriptionStatus != "active" && user.SubscriptionStatus != "trialing" {
+				writeJSON(w, http.StatusForbidden, errorResponse{
+					Error:   "SUBSCRIPTION_REQUIRED",
+					Message: "An active subscription is required to use this feature",
+				})
+				return
+			}
+
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+func GetUserID(ctx context.Context) string {
+	if v, ok := ctx.Value(UserIDKey).(string); ok {
+		return v
+	}
+	return ""
+}
+
+func GetUserEmail(ctx context.Context) string {
+	if v, ok := ctx.Value(UserEmailKey).(string); ok {
+		return v
+	}
+	return ""
+}
+
+func GetUserTier(ctx context.Context) string {
+	if v, ok := ctx.Value(UserTierKey).(string); ok {
+		return v
+	}
+	return "free"
+}

backend/internal/middleware/auth_test.go

@@ -0,0 +1,60 @@
+package middleware
+
+import (
+	"context"
+	"testing"
+)
+
+func TestGetUserID_Empty(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	if id := GetUserID(ctx); id != "" {
+		t.Errorf("expected empty user ID, got %q", id)
+	}
+}
+
+func TestGetUserID_Set(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.WithValue(context.Background(), UserIDKey, "abc-123")
+	if id := GetUserID(ctx); id != "abc-123" {
+		t.Errorf("expected abc-123, got %q", id)
+	}
+}
+
+func TestGetUserEmail_Empty(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	if email := GetUserEmail(ctx); email != "" {
+		t.Errorf("expected empty email, got %q", email)
+	}
+}
+
+func TestGetUserEmail_Set(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.WithValue(context.Background(), UserEmailKey, "test@example.com")
+	if email := GetUserEmail(ctx); email != "test@example.com" {
+		t.Errorf("expected test@example.com, got %q", email)
+	}
+}
+
+func TestGetUserTier_Default(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	if tier := GetUserTier(ctx); tier != "free" {
+		t.Errorf("expected default tier 'free', got %q", tier)
+	}
+}
+
+func TestGetUserTier_Set(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.WithValue(context.Background(), UserTierKey, "pro")
+	if tier := GetUserTier(ctx); tier != "pro" {
+		t.Errorf("expected 'pro', got %q", tier)
+	}
+}

backend/internal/models/address.go

@@ -6,7 +6,7 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgxpool"
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
 )
 
 type AddressModel struct {
@@ -55,12 +55,14 @@ func (m *AddressModel) ListByUser(ctx context.Context, userID string) ([]domain.
 	return addresses, rows.Err()
 }
 
-// ListAll returns all addresses system-wide (used by the poller).
+// ListAll returns addresses for users with an active subscription (used by the poller).
 func (m *AddressModel) ListAll(ctx context.Context) ([]domain.Address, error) {
 	rows, err := m.pool.Query(ctx,
-		`SELECT id, user_id, address, label, created_at
-		 FROM addresses
-		 ORDER BY created_at DESC`,
+		`SELECT a.id, a.user_id, a.address, a.label, a.created_at
+		 FROM addresses a
+		 JOIN users u ON u.id = a.user_id
+		 WHERE u.subscription_status IN ('active', 'trialing')
+		 ORDER BY a.created_at DESC`,
 	)
 	if err != nil {
 		return nil, err
@@ -107,6 +109,33 @@ func (m *AddressModel) FindByID(ctx context.Context, id int, userID *string) (*d
 	return &a, nil
 }
 
+// UpdateLabel updates the label for an address owned by userID.
+// Returns nil, nil if no row matched (address not found or not owned by user).
+func (m *AddressModel) UpdateLabel(ctx context.Context, id int, userID string, label *string) (*domain.Address, error) {
+	var a domain.Address
+	err := m.pool.QueryRow(ctx,
+		`UPDATE addresses SET label = $3 WHERE id = $1 AND user_id = $2
+		 RETURNING id, user_id, address, label, created_at`,
+		id, userID, label,
+	).Scan(&a.ID, &a.UserID, &a.Address, &a.Label, &a.CreatedAt)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return &a, nil
+}
+
+func (m *AddressModel) CountByUser(ctx context.Context, userID string) (int, error) {
+	var count int
+	err := m.pool.QueryRow(ctx,
+		`SELECT COUNT(*) FROM addresses WHERE user_id = $1`,
+		userID,
+	).Scan(&count)
+	return count, err
+}
+
 func (m *AddressModel) Remove(ctx context.Context, id int, userID string) (bool, error) {
 	tag, err := m.pool.Exec(ctx,
 		`DELETE FROM addresses WHERE id = $1 AND user_id = $2`,

backend/internal/models/alert_event.go

@@ -2,9 +2,11 @@ package models
 
 import (
 	"context"
+	"errors"
 
+	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgxpool"
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
 )
 
 type AlertEventModel struct {
@@ -71,10 +73,15 @@ func (m *AlertEventModel) Create(ctx context.Context, alertRuleID int, message s
 	err := m.pool.QueryRow(ctx,
 		`INSERT INTO alert_events (alert_rule_id, message, address_label, tx_hash)
 		 VALUES ($1, $2, $3, $4)
+		 ON CONFLICT DO NOTHING
 		 RETURNING id, alert_rule_id, message, address_label, tx_hash, timestamp`,
 		alertRuleID, message, addressLabel, txHash,
 	).Scan(&e.ID, &e.AlertRuleID, &e.Message, &e.AddressLabel, &e.TxHash, &e.Timestamp)
 	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			// Duplicate silently skipped by ON CONFLICT DO NOTHING
+			return nil, nil
+		}
 		return nil, err
 	}
 	return &e, nil

backend/internal/models/alert_rule.go

@@ -0,0 +1,172 @@
+package models
+
+import (
+	"context"
+	"errors"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+)
+
+type AlertRuleModel struct {
+	pool *pgxpool.Pool
+}
+
+func NewAlertRuleModel(pool *pgxpool.Pool) *AlertRuleModel {
+	return &AlertRuleModel{pool: pool}
+}
+
+func (m *AlertRuleModel) Create(ctx context.Context, addressID int, alertType domain.AlertType, threshold, minimum, maximum *float64) (*domain.AlertRule, error) {
+	var r domain.AlertRule
+	err := m.pool.QueryRow(ctx,
+		`INSERT INTO alert_rules (address_id, type, threshold, minimum, maximum, enabled)
+		 VALUES ($1, $2, $3, $4, $5, TRUE)
+		 RETURNING id, address_id, type, threshold, minimum, maximum, enabled, created_at`,
+		addressID, alertType.String(), threshold, minimum, maximum,
+	).Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Minimum, &r.Maximum, &r.Enabled, &r.CreatedAt)
+	if err != nil {
+		return nil, err
+	}
+	return &r, nil
+}
+
+func (m *AlertRuleModel) ListByAddress(ctx context.Context, addressID int) ([]domain.AlertRule, error) {
+	rows, err := m.pool.Query(ctx,
+		`SELECT id, address_id, type, threshold, minimum, maximum, enabled, created_at
+		 FROM alert_rules
+		 WHERE address_id = $1
+		 ORDER BY created_at DESC`,
+		addressID,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var rules []domain.AlertRule
+	for rows.Next() {
+		var r domain.AlertRule
+		if err := rows.Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Minimum, &r.Maximum, &r.Enabled, &r.CreatedAt); err != nil {
+			return nil, err
+		}
+		rules = append(rules, r)
+	}
+	return rules, rows.Err()
+}
+
+func (m *AlertRuleModel) FindByID(ctx context.Context, id int, userID *string) (*domain.AlertRule, error) {
+	var r domain.AlertRule
+	var err error
+
+	if userID != nil {
+		err = m.pool.QueryRow(ctx,
+			`SELECT ar.id, ar.address_id, ar.type, ar.threshold, ar.minimum, ar.maximum, ar.enabled, ar.created_at
+			 FROM alert_rules ar
+			 JOIN addresses a ON a.id = ar.address_id
+			 WHERE ar.id = $1 AND a.user_id = $2`,
+			id, *userID,
+		).Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Minimum, &r.Maximum, &r.Enabled, &r.CreatedAt)
+	} else {
+		err = m.pool.QueryRow(ctx,
+			`SELECT id, address_id, type, threshold, minimum, maximum, enabled, created_at
+			 FROM alert_rules
+			 WHERE id = $1`,
+			id,
+		).Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Minimum, &r.Maximum, &r.Enabled, &r.CreatedAt)
+	}
+
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return &r, nil
+}
+
+func (m *AlertRuleModel) UpdateEnabled(ctx context.Context, id int, enabled bool) (*domain.AlertRule, error) {
+	var r domain.AlertRule
+	err := m.pool.QueryRow(ctx,
+		`UPDATE alert_rules
+		 SET enabled = $2
+		 WHERE id = $1
+		 RETURNING id, address_id, type, threshold, minimum, maximum, enabled, created_at`,
+		id, enabled,
+	).Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Minimum, &r.Maximum, &r.Enabled, &r.CreatedAt)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return &r, nil
+}
+
+func (m *AlertRuleModel) UpdateThresholds(ctx context.Context, id int, minimum, maximum *float64) (*domain.AlertRule, error) {
+	var r domain.AlertRule
+	err := m.pool.QueryRow(ctx,
+		`UPDATE alert_rules
+		 SET minimum = $2, maximum = $3
+		 WHERE id = $1
+		 RETURNING id, address_id, type, threshold, minimum, maximum, enabled, created_at`,
+		id, minimum, maximum,
+	).Scan(&r.ID, &r.AddressID, &r.Type, &r.Threshold, &r.Minimum, &r.Maximum, &r.Enabled, &r.CreatedAt)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return &r, nil
+}
+
+func (m *AlertRuleModel) CountDistinctTypesByAddress(ctx context.Context, addressID int) (int, error) {
+	var count int
+	err := m.pool.QueryRow(ctx,
+		`SELECT COUNT(DISTINCT type) FROM alert_rules WHERE address_id = $1`,
+		addressID,
+	).Scan(&count)
+	return count, err
+}
+
+func (m *AlertRuleModel) Remove(ctx context.Context, id int) (bool, error) {
+	tag, err := m.pool.Exec(ctx,
+		`DELETE FROM alert_rules WHERE id = $1`,
+		id,
+	)
+	if err != nil {
+		return false, err
+	}
+	return tag.RowsAffected() > 0, nil
+}
+
+// DisableAllForUser sets enabled = false on every alert rule owned by addresses of userID.
+func (m *AlertRuleModel) DisableAllForUser(ctx context.Context, userID string) (int64, error) {
+	tag, err := m.pool.Exec(ctx,
+		`UPDATE alert_rules ar
+		 SET enabled = FALSE
+		 FROM addresses a
+		 WHERE ar.address_id = a.id AND a.user_id = $1`,
+		userID,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return tag.RowsAffected(), nil
+}
+
+// EnableAllForUser sets enabled = true on every alert rule owned by addresses of userID.
+func (m *AlertRuleModel) EnableAllForUser(ctx context.Context, userID string) (int64, error) {
+	tag, err := m.pool.Exec(ctx,
+		`UPDATE alert_rules ar
+		 SET enabled = TRUE
+		 FROM addresses a
+		 WHERE ar.address_id = a.id AND a.user_id = $1`,
+		userID,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return tag.RowsAffected(), nil
+}

backend/internal/models/checkpoint.go

@@ -3,10 +3,11 @@ package models
 import (
 	"context"
 	"errors"
+	"time"
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgxpool"
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
 )
 
 type CheckpointModel struct {
@@ -17,6 +18,20 @@ func NewCheckpointModel(pool *pgxpool.Pool) *CheckpointModel {
 	return &CheckpointModel{pool: pool}
 }
 
+// GetLatestBlock returns the highest last_checked_block and its timestamp across all addresses.
+// Returns nil, nil, nil when no checkpoints exist yet.
+func (m *CheckpointModel) GetLatestBlock(ctx context.Context) (*int, *time.Time, error) {
+	var block *int
+	var checkedAt *time.Time
+	err := m.pool.QueryRow(ctx,
+		`SELECT MAX(last_checked_block), MAX(last_checked_at) FROM address_checkpoints`,
+	).Scan(&block, &checkedAt)
+	if err != nil {
+		return nil, nil, err
+	}
+	return block, checkedAt, nil
+}
+
 // GetLastCheckedBlock returns the last checked block for an address, or -1 if never checked.
 func (m *CheckpointModel) GetLastCheckedBlock(ctx context.Context, addressID int) (int, bool, error) {
 	var block int

backend/internal/models/notification_config.go

@@ -6,7 +6,7 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgxpool"
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
 )
 
 type NotificationConfigModel struct {
@@ -21,12 +21,12 @@ func (m *NotificationConfigModel) GetConfig(ctx context.Context, userID string)
 	var c domain.NotificationConfig
 	err := m.pool.QueryRow(ctx,
 		`SELECT user_id, discord_webhook_url, telegram_chat_id, telegram_bot_token,
-		        email, notification_enabled, created_at, updated_at
+		        email, slack_webhook_url, notification_enabled, created_at, updated_at
 		 FROM user_notification_configs
 		 WHERE user_id = $1`,
 		userID,
 	).Scan(&c.UserID, &c.DiscordWebhookURL, &c.TelegramChatID, &c.TelegramBotToken,
-		&c.Email, &c.NotificationEnabled, &c.CreatedAt, &c.UpdatedAt)
+		&c.Email, &c.SlackWebhookURL, &c.NotificationEnabled, &c.CreatedAt, &c.UpdatedAt)
 	if err != nil {
 		if errors.Is(err, pgx.ErrNoRows) {
 			return nil, nil
@@ -40,22 +40,24 @@ func (m *NotificationConfigModel) UpsertConfig(ctx context.Context, userID strin
 	var c domain.NotificationConfig
 	err := m.pool.QueryRow(ctx,
 		`INSERT INTO user_notification_configs
-		   (user_id, discord_webhook_url, telegram_chat_id, telegram_bot_token, email, notification_enabled, updated_at)
-		 VALUES ($1, $2, $3, $4, $5, $6, NOW())
+		   (user_id, discord_webhook_url, telegram_chat_id, telegram_bot_token,
+		    email, slack_webhook_url, notification_enabled, updated_at)
+		 VALUES ($1, $2, $3, $4, $5, $6, $7, NOW())
 		 ON CONFLICT (user_id)
 		 DO UPDATE SET
-		   discord_webhook_url = COALESCE($2, user_notification_configs.discord_webhook_url),
-		   telegram_chat_id = COALESCE($3, user_notification_configs.telegram_chat_id),
-		   telegram_bot_token = COALESCE($4, user_notification_configs.telegram_bot_token),
-		   email = COALESCE($5, user_notification_configs.email),
-		   notification_enabled = $6,
+		   discord_webhook_url = $2,
+		   telegram_chat_id = $3,
+		   telegram_bot_token = $4,
+		   email = $5,
+		   slack_webhook_url = $6,
+		   notification_enabled = $7,
 		   updated_at = NOW()
 		 RETURNING user_id, discord_webhook_url, telegram_chat_id, telegram_bot_token,
-		           email, notification_enabled, created_at, updated_at`,
+		           email, slack_webhook_url, notification_enabled, created_at, updated_at`,
 		userID, cfg.DiscordWebhookURL, cfg.TelegramChatID, cfg.TelegramBotToken,
-		cfg.Email, cfg.NotificationEnabled,
+		cfg.Email, cfg.SlackWebhookURL, cfg.NotificationEnabled,
 	).Scan(&c.UserID, &c.DiscordWebhookURL, &c.TelegramChatID, &c.TelegramBotToken,
-		&c.Email, &c.NotificationEnabled, &c.CreatedAt, &c.UpdatedAt)
+		&c.Email, &c.SlackWebhookURL, &c.NotificationEnabled, &c.CreatedAt, &c.UpdatedAt)
 	if err != nil {
 		return nil, err
 	}
@@ -75,9 +77,12 @@ func (m *NotificationConfigModel) Remove(ctx context.Context, userID string) (bo
 
 func (m *NotificationConfigModel) ListEnabled(ctx context.Context) ([]domain.NotificationConfig, error) {
 	rows, err := m.pool.Query(ctx,
-		`SELECT user_id, discord_webhook_url, telegram_chat_id, email
-		 FROM user_notification_configs
-		 WHERE notification_enabled = TRUE`,
+		`SELECT nc.user_id, nc.discord_webhook_url, nc.telegram_chat_id, nc.telegram_bot_token,
+		        nc.email, nc.slack_webhook_url
+		 FROM user_notification_configs nc
+		 JOIN users u ON u.id = nc.user_id
+		 WHERE nc.notification_enabled = TRUE
+		   AND u.subscription_status IN ('active', 'trialing')`,
 	)
 	if err != nil {
 		return nil, err
@@ -87,7 +92,8 @@ func (m *NotificationConfigModel) ListEnabled(ctx context.Context) ([]domain.Not
 	var configs []domain.NotificationConfig
 	for rows.Next() {
 		var c domain.NotificationConfig
-		if err := rows.Scan(&c.UserID, &c.DiscordWebhookURL, &c.TelegramChatID, &c.Email); err != nil {
+		if err := rows.Scan(&c.UserID, &c.DiscordWebhookURL, &c.TelegramChatID,
+			&c.TelegramBotToken, &c.Email, &c.SlackWebhookURL); err != nil {
 			return nil, err
 		}
 		c.NotificationEnabled = true

backend/internal/models/user.go

@@ -0,0 +1,223 @@
+package models
+
+import (
+	"context"
+	"errors"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+)
+
+type UserModel struct {
+	pool *pgxpool.Pool
+}
+
+func NewUserModel(pool *pgxpool.Pool) *UserModel {
+	return &UserModel{pool: pool}
+}
+
+const userColumns = `id, firebase_uid, email, display_name,
+	stripe_customer_id, stripe_subscription_id, subscription_status,
+	subscription_tier, subscription_created_at, created_at, updated_at`
+
+func scanUser(row pgx.Row) (*domain.User, error) {
+	var u domain.User
+	err := row.Scan(
+		&u.ID, &u.FirebaseUID, &u.Email, &u.DisplayName,
+		&u.StripeCustomerID, &u.StripeSubscriptionID, &u.SubscriptionStatus,
+		&u.SubscriptionTier, &u.SubscriptionCreatedAt, &u.CreatedAt, &u.UpdatedAt,
+	)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil //nolint:nilnil
+		}
+		return nil, err
+	}
+	return &u, nil
+}
+
+func (m *UserModel) getByFirebaseUID(ctx context.Context, firebaseUID string) (*domain.User, error) {
+	row := m.pool.QueryRow(ctx,
+		`SELECT `+userColumns+` FROM users WHERE firebase_uid = $1`,
+		firebaseUID,
+	)
+	return scanUser(row)
+}
+
+func (m *UserModel) getByEmail(ctx context.Context, email string) (*domain.User, error) {
+	row := m.pool.QueryRow(ctx,
+		`SELECT `+userColumns+` FROM users WHERE email = $1`,
+		email,
+	)
+	return scanUser(row)
+}
+
+func isUniqueViolation(err error) bool {
+	var pgErr *pgconn.PgError
+	if errors.As(err, &pgErr) {
+		return pgErr.Code == "23505"
+	}
+	return false
+}
+
+// FindOrCreateByFirebaseUID returns the local user for a Firebase UID,
+// creating one if it doesn't exist yet.
+//
+// For onboarding races or legacy duplicate-identity states, this method
+// gracefully falls back to an existing row by email instead of failing
+// with a unique-email violation.
+func (m *UserModel) FindOrCreateByFirebaseUID(ctx context.Context, firebaseUID, email string) (*domain.User, error) {
+	existingByUID, err := m.getByFirebaseUID(ctx, firebaseUID)
+	if err != nil {
+		return nil, err
+	}
+	if existingByUID != nil {
+		return existingByUID, nil
+	}
+
+	if email != "" {
+		existingByEmail, err := m.getByEmail(ctx, email)
+		if err != nil {
+			return nil, err
+		}
+		if existingByEmail != nil {
+			return existingByEmail, nil
+		}
+	}
+
+	row := m.pool.QueryRow(ctx,
+		`INSERT INTO users (firebase_uid, email)
+		 VALUES ($1, $2)
+		 ON CONFLICT (firebase_uid) DO UPDATE SET updated_at = NOW()
+		 RETURNING `+userColumns,
+		firebaseUID, email,
+	)
+	user, err := scanUser(row)
+	if err == nil {
+		return user, nil
+	}
+
+	// If a concurrent request inserted by email or firebase_uid first,
+	// read the existing record and continue without surfacing a 500.
+	if isUniqueViolation(err) {
+		existingByUID, readErr := m.getByFirebaseUID(ctx, firebaseUID)
+		if readErr != nil {
+			return nil, readErr
+		}
+		if existingByUID != nil {
+			return existingByUID, nil
+		}
+		if email != "" {
+			existingByEmail, readErr := m.getByEmail(ctx, email)
+			if readErr != nil {
+				return nil, readErr
+			}
+			if existingByEmail != nil {
+				return existingByEmail, nil
+			}
+		}
+	}
+
+	return nil, err
+}
+
+func (m *UserModel) GetByID(ctx context.Context, id string) (*domain.User, error) {
+	row := m.pool.QueryRow(ctx,
+		`SELECT `+userColumns+` FROM users WHERE id = $1`, id,
+	)
+	return scanUser(row)
+}
+
+// GetByStripeCustomerID loads a user by their Stripe Customer ID if set.
+func (m *UserModel) GetByStripeCustomerID(ctx context.Context, stripeCustomerID string) (*domain.User, error) {
+	row := m.pool.QueryRow(ctx,
+		`SELECT `+userColumns+` FROM users WHERE stripe_customer_id = $1`,
+		stripeCustomerID,
+	)
+	return scanUser(row)
+}
+
+// ListPaidUsersWithoutActiveSubscription finds paid-tier rows whose Stripe
+// subscription is not active or trialing. Used by the periodic billing sweep.
+func (m *UserModel) ListPaidUsersWithoutActiveSubscription(ctx context.Context) ([]domain.User, error) {
+	rows, err := m.pool.Query(ctx,
+		`SELECT `+userColumns+` FROM users
+		 WHERE subscription_tier IN ('premium', 'pro')
+		   AND subscription_status NOT IN ('active', 'trialing')
+		   AND COALESCE(trim(firebase_uid), '') <> ''`,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := []domain.User{}
+	for rows.Next() {
+		var u domain.User
+		rowErr := rows.Scan(
+			&u.ID, &u.FirebaseUID, &u.Email, &u.DisplayName,
+			&u.StripeCustomerID, &u.StripeSubscriptionID, &u.SubscriptionStatus,
+			&u.SubscriptionTier, &u.SubscriptionCreatedAt, &u.CreatedAt, &u.UpdatedAt,
+		)
+		if rowErr != nil {
+			return nil, rowErr
+		}
+		out = append(out, u)
+	}
+
+	return out, rows.Err()
+}
+
+func (m *UserModel) UpdateStripeCustomer(ctx context.Context, userID, stripeCustomerID string) error {
+	_, err := m.pool.Exec(ctx,
+		`UPDATE users SET stripe_customer_id = $2, updated_at = NOW() WHERE id = $1`,
+		userID, stripeCustomerID,
+	)
+	return err
+}
+
+func (m *UserModel) ActivateSubscription(ctx context.Context, stripeCustomerID, subscriptionID, status string, tier domain.SubscriptionTier) error {
+	_, err := m.pool.Exec(ctx,
+		`UPDATE users
+		 SET stripe_subscription_id = $2,
+		     subscription_status = $3,
+		     subscription_tier = $4,
+		     subscription_created_at = COALESCE(subscription_created_at, NOW()),
+		     updated_at = NOW()
+		 WHERE stripe_customer_id = $1`,
+		stripeCustomerID, subscriptionID, status, string(tier),
+	)
+	return err
+}
+
+func (m *UserModel) UpdateSubscriptionTier(ctx context.Context, userID string, tier domain.SubscriptionTier) error {
+	_, err := m.pool.Exec(ctx,
+		`UPDATE users SET subscription_tier = $2, updated_at = NOW() WHERE id = $1`,
+		userID, string(tier),
+	)
+	return err
+}
+
+func (m *UserModel) ActivateFreeTier(ctx context.Context, userID string) error {
+	_, err := m.pool.Exec(ctx,
+		`UPDATE users
+		 SET subscription_status = 'active',
+		     subscription_tier = 'free',
+		     subscription_created_at = COALESCE(subscription_created_at, NOW()),
+		     updated_at = NOW()
+		 WHERE id = $1`,
+		userID,
+	)
+	return err
+}
+
+func (m *UserModel) UpdateSubscriptionStatus(ctx context.Context, stripeCustomerID, status string) error {
+	_, err := m.pool.Exec(ctx,
+		`UPDATE users SET subscription_status = $2, updated_at = NOW()
+		 WHERE stripe_customer_id = $1`,
+		stripeCustomerID, status,
+	)
+	return err
+}

backend/internal/notifications/discord.go

@@ -2,6 +2,7 @@ package notifications
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"fmt"
 	"log"
@@ -20,16 +21,17 @@ const (
 	colorBlue   = 0x0099ff
 )
 
-// discordHTTPClient is a shared HTTP client with a timeout for Discord requests.
 var discordHTTPClient = &http.Client{ //nolint:gochecknoglobals
 	Timeout: discordHTTPTimeoutSeconds * time.Second,
 }
 
-type AlertMetadata struct {
-	TxHash       string
-	AddressLabel string
-	AlertType    string
-	Address      string
+//  sends alert notifications via a Discord webhook.
+type DiscordNotifier struct {
+	WebhookURL string
+}
+func (d *DiscordNotifier) Send(_ context.Context, message string, meta AlertMetadata) error {
+	_, err := SendDiscordNotification(d.WebhookURL, message, meta)
+	return err
 }
 
 type discordEmbed struct {
@@ -99,8 +101,12 @@ func SendDiscordNotification(webhookURL, message string, meta AlertMetadata) (bo
 	defer resp.Body.Close()
 
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		err := fmt.Errorf("discord webhook failed: HTTP %d", resp.StatusCode)
 		log.Printf("Discord webhook failed: HTTP %d", resp.StatusCode)
-		return false, fmt.Errorf("discord webhook failed: HTTP %d", resp.StatusCode)
+		if isPermanentStatusCode(resp.StatusCode) {
+			return false, &PermanentError{Err: err}
+		}
+		return false, err
 	}
 
 	return true, nil

backend/internal/notifications/email.go

@@ -0,0 +1,214 @@
+package notifications
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"html"
+	"io"
+	"log"
+	"net/http"
+	"time"
+)
+
+type EmailNotifier struct {
+	APIKey string
+	From   string
+	To     string
+}
+
+func (e *EmailNotifier) Send(_ context.Context, message string, meta AlertMetadata) error {
+	_, err := SendEmailNotification(e.APIKey, e.From, e.To, message, meta)
+	return err
+}
+
+const emailHTTPTimeoutSeconds = 10
+
+var emailHTTPClient = &http.Client{ //nolint:gochecknoglobals
+	Timeout: emailHTTPTimeoutSeconds * time.Second,
+}
+
+type resendPayload struct {
+	From    string `json:"from"`
+	To      string `json:"to"`
+	Subject string `json:"subject"`
+	HTML    string `json:"html"`
+}
+
+func SendEmailNotification(apiKey, fromAddress, toAddress, message string, meta AlertMetadata) (bool, error) {
+	if apiKey == "" {
+		log.Printf("Skipping email notification: RESEND_API_KEY not configured")
+		return false, nil
+	}
+
+	subject := fmt.Sprintf("Koin Ping Alert: %s", alertTypeLabel(meta.AlertType))
+
+	txLink := ""
+	if meta.TxHash != "" {
+		txLink = fmt.Sprintf(
+			`<p><a href="https://etherscan.io/tx/%s">View on Etherscan</a></p>`,
+			meta.TxHash,
+		)
+	}
+
+	html := fmt.Sprintf(`
+<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
+  <h2 style="color: #333;">Koin Ping Alert</h2>
+  <p style="font-size: 16px;">%s</p>
+  <table style="margin: 16px 0; border-collapse: collapse;">
+    <tr>
+      <td style="padding: 4px 12px 4px 0; color: #666;">Address</td>
+      <td style="padding: 4px 0;">%s</td>
+    </tr>
+    <tr>
+      <td style="padding: 4px 12px 4px 0; color: #666;">Blockchain</td>
+      <td style="padding: 4px 0; font-family: monospace; font-size: 13px;">%s</td>
+    </tr>
+  </table>
+  %s
+  <hr style="border: none; border-top: 1px solid #eee; margin: 24px 0;" />
+  <p style="font-size: 12px; color: #999;">Sent by Koin Ping</p>
+</div>`,
+		message, meta.AddressLabel, meta.Address, txLink)
+
+	payload := resendPayload{
+		From:    fromAddress,
+		To:      toAddress,
+		Subject: subject,
+		HTML:    html,
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return false, fmt.Errorf("marshal email payload: %w", err)
+	}
+
+	req, err := http.NewRequest(http.MethodPost, "https://api.resend.com/emails", bytes.NewReader(body))
+	if err != nil {
+		return false, fmt.Errorf("create email request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+apiKey)
+
+	resp, err := emailHTTPClient.Do(req)
+	if err != nil {
+		log.Printf("Failed to send email notification: %v", err)
+		return false, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		err := fmt.Errorf("resend API failed: HTTP %d", resp.StatusCode)
+		log.Printf("Resend API failed: HTTP %d", resp.StatusCode)
+		if isPermanentStatusCode(resp.StatusCode) {
+			return false, &PermanentError{Err: err}
+		}
+		return false, err
+	}
+
+	return true, nil
+}
+
+func TestEmailNotification(apiKey, fromAddress, toAddress string) (bool, error) {
+	if apiKey == "" {
+		return false, fmt.Errorf("email not configured: RESEND_API_KEY not set") //nolint:err113
+	}
+
+	payload := resendPayload{
+		From:    fromAddress,
+		To:      toAddress,
+		Subject: "Koin Ping — Test Notification",
+		HTML:    `<p>Your email alerts are configured correctly!</p><p style="font-size:12px;color:#999;">Sent by Koin Ping</p>`,
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return false, err
+	}
+
+	req, err := http.NewRequest(http.MethodPost, "https://api.resend.com/emails", bytes.NewReader(body))
+	if err != nil {
+		return false, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+apiKey)
+
+	resp, err := emailHTTPClient.Do(req)
+	if err != nil {
+		log.Printf("Email test failed: %v", err)
+		return false, err
+	}
+	defer resp.Body.Close()
+
+	return resp.StatusCode >= 200 && resp.StatusCode < 300, nil
+}
+
+func alertTypeLabel(alertType string) string {
+	switch alertType {
+	case "incoming_tx":
+		return "Incoming Transaction"
+	case "outgoing_tx":
+		return "Outgoing Transaction"
+	case "large_transfer":
+		return "Large Transfer"
+	case "balance_below":
+		return "Balance Below Threshold"
+	default:
+		return "Alert"
+	}
+}
+
+type resendSupportPayload struct {
+	From    string `json:"from"`
+	To      string `json:"to"`
+	Subject string `json:"subject"`
+	Text    string `json:"text"`
+	HTML    string `json:"html"`
+}
+
+// SendSupportEmail delivers a plain-text support request via Resend (HTML copy is escaped).
+func SendSupportEmail(apiKey, fromAddress, toAddress, subject, plainBody string) error {
+	if apiKey == "" {
+		return fmt.Errorf("RESEND_API_KEY not set") //nolint:err113
+	}
+
+	escaped := html.EscapeString(plainBody)
+	htmlBody := `<pre style="font-family:ui-sans-serif,system-ui,sans-serif;white-space:pre-wrap;">` +
+		escaped + `</pre>`
+
+	payload := resendSupportPayload{
+		From:    fromAddress,
+		To:      toAddress,
+		Subject: subject,
+		Text:    plainBody,
+		HTML:    htmlBody,
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal support email payload: %w", err)
+	}
+
+	req, err := http.NewRequest(http.MethodPost, "https://api.resend.com/emails", bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("create support email request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+apiKey)
+
+	resp, err := emailHTTPClient.Do(req)
+	if err != nil {
+		log.Printf("Failed to send support email: %v", err)
+		return err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 2048))
+		log.Printf("Resend support email failed: HTTP %d body: %s", resp.StatusCode, string(snippet))
+		return fmt.Errorf("resend API failed: HTTP %d: %s", resp.StatusCode, string(snippet)) //nolint:err113
+	}
+
+	return nil
+}

backend/internal/notifications/notifier.go

@@ -0,0 +1,38 @@
+package notifications
+
+import (
+	"context"
+	"errors"
+	"net/http"
+)
+
+// AlertMetadata holds context about the alert being sent.
+type AlertMetadata struct {
+	TxHash       string
+	AddressLabel string
+	AlertType    string
+	Address      string
+}
+
+type Notifier interface {
+	Send(ctx context.Context, message string, meta AlertMetadata) error
+}
+
+// PermanentError wraps errors that should not be retried (e.g. 401, 403, 404).
+type PermanentError struct{ Err error }
+
+func (e *PermanentError) Error() string { return e.Err.Error() }
+func (e *PermanentError) Unwrap() error { return e.Err }
+
+func IsPermanent(err error) bool {
+	var p *PermanentError
+	return errors.As(err, &p)
+}
+
+func isPermanentStatusCode(code int) bool {
+	return code == http.StatusUnauthorized ||
+		code == http.StatusForbidden ||
+		code == http.StatusNotFound ||
+		code == http.StatusMethodNotAllowed ||
+		code == http.StatusGone
+}

backend/internal/notifications/slack.go

@@ -0,0 +1,132 @@
+package notifications
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+)
+
+// SlackNotifier sends alert notifications via a Slack webhook.
+type SlackNotifier struct {
+	WebhookURL string
+}
+
+// Send implements Notifier for Slack.
+func (s *SlackNotifier) Send(_ context.Context, message string, meta AlertMetadata) error {
+	_, err := SendSlackNotification(s.WebhookURL, message, meta)
+	return err
+}
+
+const slackHTTPTimeoutSeconds = 10
+
+var slackHTTPClient = &http.Client{ //nolint:gochecknoglobals
+	Timeout: slackHTTPTimeoutSeconds * time.Second,
+}
+
+type slackAttachment struct {
+	Color  string        `json:"color"`
+	Title  string        `json:"title"`
+	Text   string        `json:"text"`
+	Fields []slackField  `json:"fields"`
+	Footer string        `json:"footer"`
+	Ts     int64         `json:"ts"`
+}
+
+type slackField struct {
+	Title string `json:"title"`
+	Value string `json:"value"`
+	Short bool   `json:"short"`
+}
+
+type slackPayload struct {
+	Text        string            `json:"text,omitempty"`
+	Attachments []slackAttachment `json:"attachments,omitempty"`
+}
+
+func SendSlackNotification(webhookURL, message string, meta AlertMetadata) (bool, error) {
+	fields := []slackField{
+		{Title: "Address", Value: meta.AddressLabel, Short: true},
+		{Title: "Blockchain Address", Value: fmt.Sprintf("`%s`", meta.Address), Short: false},
+	}
+
+	if meta.TxHash != "" {
+		fields = append(fields, slackField{
+			Title: "Transaction",
+			Value: fmt.Sprintf("<https://etherscan.io/tx/%s|View on Etherscan>", meta.TxHash),
+			Short: false,
+		})
+	}
+
+	payload := slackPayload{
+		Attachments: []slackAttachment{
+			{
+				Color:  slackColorForAlertType(meta.AlertType),
+				Title:  "Koin Ping Alert",
+				Text:   message,
+				Fields: fields,
+				Footer: "Koin Ping",
+				Ts:     time.Now().Unix(),
+			},
+		},
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return false, fmt.Errorf("marshal slack payload: %w", err)
+	}
+
+	resp, err := slackHTTPClient.Post(webhookURL, "application/json", bytes.NewReader(body))
+	if err != nil {
+		log.Printf("Failed to send Slack notification: %v", err)
+		return false, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		err := fmt.Errorf("slack webhook failed: HTTP %d", resp.StatusCode)
+		log.Printf("Slack webhook failed: HTTP %d", resp.StatusCode)
+		if isPermanentStatusCode(resp.StatusCode) {
+			return false, &PermanentError{Err: err}
+		}
+		return false, err
+	}
+
+	return true, nil
+}
+
+func TestSlackWebhook(webhookURL string) (bool, error) {
+	payload := slackPayload{
+		Text: "Koin Ping test notification — Your Slack alerts are configured correctly!",
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return false, err
+	}
+
+	resp, err := slackHTTPClient.Post(webhookURL, "application/json", bytes.NewReader(body))
+	if err != nil {
+		log.Printf("Slack webhook test failed: %v", err)
+		return false, err
+	}
+	defer resp.Body.Close()
+
+	return resp.StatusCode >= 200 && resp.StatusCode < 300, nil
+}
+
+func slackColorForAlertType(alertType string) string {
+	switch alertType {
+	case "incoming_tx":
+		return "#00ff00"
+	case "outgoing_tx":
+		return "#ff9900"
+	case "large_transfer", "balance_below":
+		return "#ff0000"
+	default:
+		return "#0099ff"
+	}
+}

backend/internal/notifications/telegram.go

@@ -0,0 +1,126 @@
+package notifications
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+)
+
+// TelegramNotifier sends alert notifications via Telegram.
+type TelegramNotifier struct {
+	BotToken string
+	ChatID   string
+}
+
+// Send implements Notifier for Telegram.
+func (t *TelegramNotifier) Send(_ context.Context, message string, meta AlertMetadata) error {
+	_, err := SendTelegramNotification(t.BotToken, t.ChatID, message, meta)
+	return err
+}
+
+const telegramHTTPTimeoutSeconds = 10
+
+var telegramHTTPClient = &http.Client{ //nolint:gochecknoglobals
+	Timeout: telegramHTTPTimeoutSeconds * time.Second,
+}
+
+type telegramPayload struct {
+	ChatID    string `json:"chat_id"`
+	Text      string `json:"text"`
+	ParseMode string `json:"parse_mode"`
+}
+
+func SendTelegramNotification(botToken, chatID, message string, meta AlertMetadata) (bool, error) {
+	text := fmt.Sprintf("*Koin Ping Alert*\n\n%s\n\n*Address:* %s\n`%s`",
+		escapeMarkdown(message), escapeMarkdown(meta.AddressLabel), meta.Address)
+
+	if meta.TxHash != "" {
+		text += fmt.Sprintf("\n\n[View on Etherscan](https://etherscan.io/tx/%s)", meta.TxHash)
+	}
+
+	payload := telegramPayload{
+		ChatID:    chatID,
+		Text:      text,
+		ParseMode: "Markdown",
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return false, fmt.Errorf("marshal telegram payload: %w", err)
+	}
+
+	url := fmt.Sprintf("https://api.telegram.org/bot%s/sendMessage", botToken)
+
+	resp, err := telegramHTTPClient.Post(url, "application/json", bytes.NewReader(body))
+	if err != nil {
+		log.Printf("Failed to send Telegram notification: %v", err)
+		return false, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		err := fmt.Errorf("telegram API failed: HTTP %d", resp.StatusCode)
+		log.Printf("Telegram API failed: HTTP %d", resp.StatusCode)
+		if isPermanentStatusCode(resp.StatusCode) {
+			return false, &PermanentError{Err: err}
+		}
+		return false, err
+	}
+
+	return true, nil
+}
+
+func TestTelegramWebhook(botToken, chatID string) (bool, error) {
+	payload := telegramPayload{
+		ChatID:    chatID,
+		Text:      "Koin Ping test notification — Your Telegram alerts are configured correctly!",
+		ParseMode: "Markdown",
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return false, err
+	}
+
+	url := fmt.Sprintf("https://api.telegram.org/bot%s/sendMessage", botToken)
+
+	resp, err := telegramHTTPClient.Post(url, "application/json", bytes.NewReader(body))
+	if err != nil {
+		log.Printf("Telegram test failed: %v", err)
+		return false, err
+	}
+	defer resp.Body.Close()
+
+	return resp.StatusCode >= 200 && resp.StatusCode < 300, nil
+}
+
+func escapeMarkdown(s string) string {
+	replacer := []struct{ old, new string }{
+		{"_", "\\_"}, {"*", "\\*"}, {"[", "\\["}, {"]", "\\]"},
+		{"(", "\\("}, {")", "\\)"}, {"~", "\\~"}, {"`", "\\`"},
+		{">", "\\>"}, {"#", "\\#"}, {"+", "\\+"}, {"-", "\\-"},
+		{"=", "\\="}, {"|", "\\|"}, {"{", "\\{"}, {"}", "\\}"},
+		{".", "\\."}, {"!", "\\!"},
+	}
+	result := s
+	for _, r := range replacer {
+		result = replaceAll(result, r.old, r.new)
+	}
+	return result
+}
+
+func replaceAll(s, old, new string) string {
+	out := ""
+	for i := 0; i < len(s); i++ {
+		if string(s[i]) == old {
+			out += new
+		} else {
+			out += string(s[i])
+		}
+	}
+	return out
+}

backend/internal/protocols/ethereum/jsonrpc.go

@@ -0,0 +1,421 @@
+package ethereum
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log"
+	"math/big"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+)
+
+const (
+	rpcTimeoutMS      = 30000
+	rpcMaxRetries     = 3
+	rpcRetryBaseMS    = 2000
+	rpcMinIntervalMS  = 1000
+)
+
+type JsonRpcEthereum struct {
+	rpcURL     string
+	client     *http.Client
+	lastCallAt time.Time
+}
+
+func NewJsonRpcEthereum(rpcURL string) (*JsonRpcEthereum, error) {
+	if rpcURL == "" {
+		return nil, fmt.Errorf("JsonRpcEthereum requires a valid RPC URL")
+	}
+	return &JsonRpcEthereum{
+		rpcURL: rpcURL,
+		client: &http.Client{
+			Timeout: time.Duration(rpcTimeoutMS) * time.Millisecond,
+		},
+	}, nil
+}
+
+type rpcRequest struct {
+	JSONRPC string        `json:"jsonrpc"`
+	ID      int64         `json:"id"`
+	Method  string        `json:"method"`
+	Params  []interface{} `json:"params"`
+}
+
+type rpcResponse struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      int64           `json:"id"`
+	Result  json.RawMessage `json:"result"`
+	Error   *rpcError       `json:"error"`
+}
+
+type rpcError struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+}
+
+func (j *JsonRpcEthereum) callRPC(ctx context.Context, method string, params ...interface{}) (json.RawMessage, error) {
+	j.throttle(ctx)
+
+	if params == nil {
+		params = []interface{}{}
+	}
+
+	body, err := json.Marshal(rpcRequest{
+		JSONRPC: "2.0",
+		ID:      time.Now().UnixMilli(),
+		Method:  method,
+		Params:  params,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("marshal RPC request: %w", err)
+	}
+
+	result, callErr := j.callWithRetry(ctx, method, body)
+	j.lastCallAt = time.Now()
+
+	return result, callErr
+}
+
+func (j *JsonRpcEthereum) throttle(ctx context.Context) {
+	if j.lastCallAt.IsZero() {
+		return
+	}
+	minInterval := time.Duration(rpcMinIntervalMS) * time.Millisecond
+	elapsed := time.Since(j.lastCallAt)
+	if elapsed >= minInterval {
+		return
+	}
+	select {
+	case <-ctx.Done():
+	case <-time.After(minInterval - elapsed):
+	}
+}
+
+// callWithRetry executes a JSON-RPC POST with exponential backoff on transient errors.
+// It retries on network errors, HTTP 429, and HTTP 5xx. It does NOT retry on RPC-level
+// errors or other 4xx responses (those are permanent failures).
+func (j *JsonRpcEthereum) callWithRetry(ctx context.Context, method string, body []byte) (json.RawMessage, error) {
+	var lastErr error
+	for attempt := range rpcMaxRetries {
+		if attempt > 0 {
+			wait := time.Duration(rpcRetryBaseMS*(1<<(attempt-1))) * time.Millisecond
+			select {
+			case <-ctx.Done():
+				return nil, ctx.Err()
+			case <-time.After(wait):
+			}
+			log.Printf("Retrying RPC call [%s] (attempt %d/%d)", method, attempt+1, rpcMaxRetries)
+		}
+
+		result, err := j.doRPCCall(ctx, method, body)
+		if err == nil {
+			return result, nil
+		}
+
+		lastErr = err
+
+		// Permanent errors: do not retry
+		if isPermanentRPCError(err) {
+			return nil, err
+		}
+
+		log.Printf("Transient RPC error [%s] (attempt %d/%d): %v", method, attempt+1, rpcMaxRetries, err)
+	}
+
+	return nil, lastErr
+}
+
+func (j *JsonRpcEthereum) doRPCCall(ctx context.Context, method string, body []byte) (json.RawMessage, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, j.rpcURL, bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("create RPC request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := j.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("RPC call failed [%s]: %w", method, err)
+	}
+	defer resp.Body.Close()
+
+	// 429 and 5xx are transient; other non-200 are permanent.
+	if resp.StatusCode != http.StatusOK {
+		err := fmt.Errorf("HTTP %d: %s for %s", resp.StatusCode, resp.Status, method)
+		if resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= 500 { //nolint:mnd
+			return nil, err // transient — will be retried
+		}
+		return nil, &permanentRPCError{err}
+	}
+
+	var rpcResp rpcResponse
+	if err := json.NewDecoder(resp.Body).Decode(&rpcResp); err != nil {
+		return nil, fmt.Errorf("decode RPC response: %w", err)
+	}
+
+	if rpcResp.Error != nil {
+		// RPC-level errors are permanent (bad params, unsupported method, etc.)
+		return nil, &permanentRPCError{
+			fmt.Errorf("RPC Error [%s]: %s (code: %d)", method, rpcResp.Error.Message, rpcResp.Error.Code),
+		}
+	}
+
+	return rpcResp.Result, nil
+}
+
+type permanentRPCError struct{ cause error }
+
+func (e *permanentRPCError) Error() string { return e.cause.Error() }
+func (e *permanentRPCError) Unwrap() error { return e.cause }
+
+func isPermanentRPCError(err error) bool {
+	var p *permanentRPCError
+	return errors.As(err, &p)
+}
+
+func (j *JsonRpcEthereum) GetLatestBlockNumber(ctx context.Context) (int, error) {
+	result, err := j.callRPC(ctx, "eth_blockNumber")
+	if err != nil {
+		return 0, err
+	}
+
+	var hexBlock string
+	if err := json.Unmarshal(result, &hexBlock); err != nil {
+		return 0, fmt.Errorf("unmarshal block number: %w", err)
+	}
+
+	return hexToInt(hexBlock)
+}
+
+type rpcBlock struct {
+	Timestamp    string  `json:"timestamp"`
+	Transactions []rpcTx `json:"transactions"`
+}
+
+type rpcTx struct {
+	Hash        string  `json:"hash"`
+	From        string  `json:"from"`
+	To          *string `json:"to"`
+	Value       string  `json:"value"`
+	BlockNumber string  `json:"blockNumber"`
+}
+
+func (j *JsonRpcEthereum) GetBlockTransactions(ctx context.Context, blockNumber int) ([]domain.NormalizedTx, error) {
+	hexBlock := fmt.Sprintf("0x%x", blockNumber)
+
+	result, err := j.callRPC(ctx, "eth_getBlockByNumber", hexBlock, true)
+	if err != nil {
+		return nil, err
+	}
+
+	if string(result) == "null" {
+		return nil, nil
+	}
+
+	var block rpcBlock
+	if err := json.Unmarshal(result, &block); err != nil {
+		return nil, fmt.Errorf("unmarshal block: %w", err)
+	}
+
+	blockTimestamp, err := hexToInt64(block.Timestamp)
+	if err != nil {
+		return nil, fmt.Errorf("parse block timestamp: %w", err)
+	}
+
+	txs := make([]domain.NormalizedTx, 0, len(block.Transactions))
+	for _, tx := range block.Transactions {
+		bn, _ := hexToInt(tx.BlockNumber)
+
+		var toLower *string
+		if tx.To != nil {
+			s := strings.ToLower(*tx.To)
+			toLower = &s
+		}
+
+		txs = append(txs, domain.NormalizedTx{
+			Hash:           tx.Hash,
+			From:           strings.ToLower(tx.From),
+			To:             toLower,
+			Value:          hexToDecimalString(tx.Value),
+			BlockNumber:    bn,
+			BlockTimestamp: blockTimestamp,
+		})
+	}
+
+	return txs, nil
+}
+
+func (j *JsonRpcEthereum) GetBalance(ctx context.Context, address string) (string, error) {
+	result, err := j.callRPC(ctx, "eth_getBalance", address, "latest")
+	if err != nil {
+		return "", err
+	}
+
+	var hexBalance string
+	if err := json.Unmarshal(result, &hexBalance); err != nil {
+		return "", fmt.Errorf("unmarshal balance: %w", err)
+	}
+
+	return hexToDecimalString(hexBalance), nil
+}
+
+const erc20TransferTopic = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+
+const minTransferTopics = 3
+
+type rpcLog struct {
+	Address     string   `json:"address"`
+	Topics      []string `json:"topics"`
+	Data        string   `json:"data"`
+	BlockNumber string   `json:"blockNumber"`
+	TxHash      string   `json:"transactionHash"`
+}
+
+// GetTokenTransfers fetches ERC-20 Transfer events for a given address
+// across a block range, covering both incoming and outgoing transfers.
+func (j *JsonRpcEthereum) GetTokenTransfers(ctx context.Context, fromBlock, toBlock int, address string) ([]domain.NormalizedTx, error) {
+	paddedAddr := padAddress(address)
+	hexFrom := fmt.Sprintf("0x%x", fromBlock)
+	hexTo := fmt.Sprintf("0x%x", toBlock)
+
+	incomingLogs, err := j.getTransferLogs(ctx, hexFrom, hexTo, "", paddedAddr)
+	if err != nil {
+		return nil, fmt.Errorf("fetch incoming token transfers: %w", err)
+	}
+
+	outgoingLogs, err := j.getTransferLogs(ctx, hexFrom, hexTo, paddedAddr, "")
+	if err != nil {
+		return nil, fmt.Errorf("fetch outgoing token transfers: %w", err)
+	}
+
+	seen := make(map[string]bool)
+	var txs []domain.NormalizedTx
+
+	for _, entry := range append(incomingLogs, outgoingLogs...) {
+		key := entry.TxHash + "|" + entry.Address + "|" + entry.Data
+		if seen[key] {
+			continue
+		}
+		seen[key] = true
+
+		tx, parseErr := parseTransferLog(entry)
+		if parseErr != nil {
+			log.Printf("Skipping unparseable transfer log in tx %s: %v", entry.TxHash, parseErr)
+			continue
+		}
+		txs = append(txs, tx)
+	}
+
+	return txs, nil
+}
+
+func (j *JsonRpcEthereum) getTransferLogs(ctx context.Context, fromBlock, toBlock, fromAddr, toAddr string) ([]rpcLog, error) {
+	topics := make([]interface{}, minTransferTopics)
+	topics[0] = erc20TransferTopic
+
+	if fromAddr != "" {
+		topics[1] = fromAddr
+	}
+	if toAddr != "" {
+		topics[2] = toAddr
+	}
+
+	filter := map[string]interface{}{
+		"fromBlock": fromBlock,
+		"toBlock":   toBlock,
+		"topics":    topics,
+	}
+
+	result, err := j.callRPC(ctx, "eth_getLogs", filter)
+	if err != nil {
+		return nil, err
+	}
+
+	var logs []rpcLog
+	if err := json.Unmarshal(result, &logs); err != nil {
+		return nil, fmt.Errorf("unmarshal logs: %w", err)
+	}
+
+	return logs, nil
+}
+
+func parseTransferLog(entry rpcLog) (domain.NormalizedTx, error) {
+	if len(entry.Topics) < minTransferTopics {
+		return domain.NormalizedTx{}, fmt.Errorf("transfer log has %d topics, expected >= 3", len(entry.Topics))
+	}
+
+	from := topicToAddress(entry.Topics[1])
+	to := topicToAddress(entry.Topics[2])
+	tokenValue := hexToDecimalString(entry.Data)
+	blockNumber, _ := hexToInt(entry.BlockNumber)
+
+	contractAddr := strings.ToLower(entry.Address)
+	tokenInfo, known := LookupToken(contractAddr)
+
+	tx := domain.NormalizedTx{
+		Hash:          entry.TxHash,
+		From:          from,
+		To:            &to,
+		Value:         "0",
+		BlockNumber:   blockNumber,
+		TokenContract: &contractAddr,
+		TokenValue:    &tokenValue,
+	}
+
+	if known {
+		tx.TokenSymbol = &tokenInfo.Symbol
+		tx.TokenDecimals = &tokenInfo.Decimals
+	}
+
+	return tx, nil
+}
+
+func padAddress(addr string) string {
+	clean := strings.TrimPrefix(strings.ToLower(addr), "0x")
+	const addressHexLen = 64
+	return "0x" + strings.Repeat("0", addressHexLen-len(clean)) + clean
+}
+
+func topicToAddress(topic string) string {
+	clean := strings.TrimPrefix(topic, "0x")
+	const ethAddrLen = 40
+	if len(clean) > ethAddrLen {
+		clean = clean[len(clean)-ethAddrLen:]
+	}
+	return "0x" + strings.ToLower(clean)
+}
+
+func hexToInt(hex string) (int, error) {
+	hex = strings.TrimPrefix(hex, "0x")
+	n, ok := new(big.Int).SetString(hex, 16)
+	if !ok {
+		return 0, fmt.Errorf("invalid hex: %s", hex)
+	}
+	return int(n.Int64()), nil
+}
+
+func hexToInt64(hex string) (int64, error) {
+	hex = strings.TrimPrefix(hex, "0x")
+	n, ok := new(big.Int).SetString(hex, 16)
+	if !ok {
+		return 0, fmt.Errorf("invalid hex: %s", hex)
+	}
+	return n.Int64(), nil
+}
+
+func hexToDecimalString(hex string) string {
+	if hex == "" || hex == "0x" || hex == "0x0" {
+		return "0"
+	}
+	clean := strings.TrimPrefix(hex, "0x")
+	n, ok := new(big.Int).SetString(clean, 16)
+	if !ok {
+		return "0"
+	}
+	return n.String()
+}

backend/internal/protocols/ethereum/observer.go

@@ -3,7 +3,7 @@ package ethereum
 import (
 	"context"
 
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
 )
 
 // EthereumObserver defines the interface for blockchain interaction.
@@ -12,4 +12,5 @@ type EthereumObserver interface {
 	GetLatestBlockNumber(ctx context.Context) (int, error)
 	GetBlockTransactions(ctx context.Context, blockNumber int) ([]domain.NormalizedTx, error)
 	GetBalance(ctx context.Context, address string) (string, error)
+	GetTokenTransfers(ctx context.Context, fromBlock, toBlock int, address string) ([]domain.NormalizedTx, error)
 }

backend/internal/protocols/ethereum/tokens.go

@@ -0,0 +1,34 @@
+package ethereum
+
+import "strings"
+
+// TokenInfo holds metadata for a known ERC-20 token contract.
+type TokenInfo struct {
+	Symbol   string
+	Decimals int
+}
+
+//nolint:gochecknoglobals
+var wellKnownTokens = map[string]TokenInfo{
+	"0xdac17f958d2ee523a2206206994597c13d831ec7": {Symbol: "USDT", Decimals: 6},
+	"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": {Symbol: "USDC", Decimals: 6},
+	"0x6b175474e89094c44da98b954eedeac495271d0f": {Symbol: "DAI", Decimals: 18},
+	"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": {Symbol: "WETH", Decimals: 18},
+	"0x2260fac5e5542a773aa44fbcfedf7c193bc2c599": {Symbol: "WBTC", Decimals: 8},
+	"0x514910771af9ca656af840dff83e8264ecf986ca": {Symbol: "LINK", Decimals: 18},
+	"0x1f9840a85d5af5bf1d1762f925bdaddc4201f984": {Symbol: "UNI", Decimals: 18},
+	"0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9": {Symbol: "AAVE", Decimals: 18},
+	"0x95ad61b0a150d79219dcf64e1e6cc01f0b64c4ce": {Symbol: "SHIB", Decimals: 18},
+	"0x6982508145454ce325ddbe47a25d4ec3d2311933": {Symbol: "PEPE", Decimals: 18},
+	"0xb8c77482e45f1f44de1745f52c74426c631bdd52": {Symbol: "BNB", Decimals: 18},
+	"0x4fabb145d64652a948d72533023f6e7a623c7c53": {Symbol: "BUSD", Decimals: 18},
+	"0x75231f58b43240c9718dd58b4967c5114342a86c": {Symbol: "OKB", Decimals: 18},
+	"0x582d872a1b094fc48f5de31d3b73f2d9be47def1": {Symbol: "TON", Decimals: 9},
+	"0x4d224452801aced8b2f0aebe155379bb5d594381": {Symbol: "APE", Decimals: 18},
+}
+
+// LookupToken returns metadata for a known token contract, if found.
+func LookupToken(contractAddress string) (TokenInfo, bool) {
+	info, ok := wellKnownTokens[strings.ToLower(contractAddress)]
+	return info, ok
+}

backend/internal/services/email_digest.go

@@ -0,0 +1,196 @@
+package services
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/kjannette/koin-ping/backend/internal/models"
+)
+
+const (
+	resendAPIURL          = "https://api.resend.com/emails"
+	emailHTTPTimeout      = 10 * time.Second
+	defaultDigestMaxItems = 50
+)
+
+var digestHTTPClient = &http.Client{Timeout: emailHTTPTimeout} //nolint:gochecknoglobals
+
+// handles email setup and digest sending via Resend.
+type EmailDigestService struct {
+	apiKey      string
+	fromAddress string
+	alertEvents *models.AlertEventModel
+	notifCfgs   *models.NotificationConfigModel
+}
+
+func NewEmailDigestService(
+	apiKey, fromAddress string,
+	alertEvents *models.AlertEventModel,
+	notifCfgs *models.NotificationConfigModel,
+) *EmailDigestService {
+	return &EmailDigestService{
+		apiKey:      apiKey,
+		fromAddress: fromAddress,
+		alertEvents: alertEvents,
+		notifCfgs:   notifCfgs,
+	}
+}
+
+// Configured returns true when the Resend API key is present.
+func (s *EmailDigestService) Configured() bool {
+	return s.apiKey != ""
+}
+
+// SetupEmail validates the email works by sending a welcome/confirmation
+// message via Resend. Called when a user saves their email in notification settings.
+func (s *EmailDigestService) SetupEmail(toAddress string) error {
+	if !s.Configured() {
+		return fmt.Errorf("email service not configured: RESEND_API_KEY not set") //nolint:err113
+	}
+
+	html := `
+<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
+  <h2 style="color: #333;">Welcome to Koin Ping Email Alerts</h2>
+  <p>Your email has been successfully configured for alert notifications.</p>
+  <p>You will receive alert digests at this address when events are triggered
+     on your watched addresses.</p>
+  <hr style="border: none; border-top: 1px solid #eee; margin: 24px 0;" />
+  <p style="font-size: 12px; color: #999;">Sent by Koin Ping</p>
+</div>`
+
+	return s.send(toAddress, "Koin Ping — Email Alerts Configured", html)
+}
+
+func (s *EmailDigestService) SendDigest(ctx context.Context, userID, toAddress string) error {
+	if !s.Configured() {
+		return fmt.Errorf("email service not configured: RESEND_API_KEY not set") //nolint:err113
+	}
+
+	events, err := s.alertEvents.ListRecentByUser(ctx, userID, defaultDigestMaxItems)
+	if err != nil {
+		return fmt.Errorf("fetch alert events: %w", err)
+	}
+
+	if len(events) == 0 {
+		log.Printf("No recent alerts for user %s — skipping digest", userID)
+		return nil
+	}
+
+	var rows string
+	for _, e := range events {
+		label := "—"
+		if e.AddressLabel != nil {
+			label = *e.AddressLabel
+		}
+		txLink := "—"
+		if e.TxHash != nil {
+			txLink = fmt.Sprintf(
+				`<a href="https://etherscan.io/tx/%s" style="color:#0066cc;">%s…</a>`,
+				*e.TxHash, (*e.TxHash)[:10],
+			)
+		}
+		rows += fmt.Sprintf(`
+      <tr>
+        <td style="padding:6px 8px; border-bottom:1px solid #eee;">%s</td>
+        <td style="padding:6px 8px; border-bottom:1px solid #eee;">%s</td>
+        <td style="padding:6px 8px; border-bottom:1px solid #eee;">%s</td>
+        <td style="padding:6px 8px; border-bottom:1px solid #eee; font-size:12px; color:#666;">%s</td>
+      </tr>`,
+			label, e.Message, txLink,
+			e.Timestamp.Format("Jan 2 15:04 UTC"),
+		)
+	}
+
+	html := fmt.Sprintf(`
+<div style="font-family: sans-serif; max-width: 700px; margin: 0 auto;">
+  <h2 style="color: #333;">Koin Ping — Alert Digest</h2>
+  <p>Here are your recent alerts (%d total):</p>
+  <table style="width:100%%; border-collapse:collapse; font-size:14px;">
+    <thead>
+      <tr style="background:#f5f5f5;">
+        <th style="padding:8px; text-align:left;">Address</th>
+        <th style="padding:8px; text-align:left;">Alert</th>
+        <th style="padding:8px; text-align:left;">Tx</th>
+        <th style="padding:8px; text-align:left;">Time</th>
+      </tr>
+    </thead>
+    <tbody>%s</tbody>
+  </table>
+  <hr style="border:none; border-top:1px solid #eee; margin:24px 0;" />
+  <p style="font-size:12px; color:#999;">Sent by Koin Ping</p>
+</div>`, len(events), rows)
+
+	subject := fmt.Sprintf("Koin Ping Digest — %d alerts", len(events))
+
+	return s.send(toAddress, subject, html)
+}
+
+func (s *EmailDigestService) SendDigestsForAllUsers(ctx context.Context) (int, error) {
+	if !s.Configured() {
+		return 0, nil
+	}
+
+	configs, err := s.notifCfgs.ListEnabled(ctx)
+	if err != nil {
+		return 0, fmt.Errorf("list enabled configs: %w", err)
+	}
+
+	sent := 0
+	for _, cfg := range configs {
+		if cfg.Email == nil || *cfg.Email == "" {
+			continue
+		}
+		if err := s.SendDigest(ctx, cfg.UserID, *cfg.Email); err != nil {
+			log.Printf("Failed to send digest to user %s: %v", cfg.UserID, err)
+			continue
+		}
+		sent++
+	}
+
+	return sent, nil
+}
+
+type resendEmailPayload struct {
+	From    string `json:"from"`
+	To      string `json:"to"`
+	Subject string `json:"subject"`
+	HTML    string `json:"html"`
+}
+
+func (s *EmailDigestService) send(to, subject, html string) error {
+	payload := resendEmailPayload{
+		From:    s.fromAddress,
+		To:      to,
+		Subject: subject,
+		HTML:    html,
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal email payload: %w", err)
+	}
+
+	req, err := http.NewRequest(http.MethodPost, resendAPIURL, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+s.apiKey)
+
+	resp, err := digestHTTPClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("send email via Resend: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("Resend API returned HTTP %d", resp.StatusCode) //nolint:err113
+	}
+
+	return nil
+}

backend/internal/services/evaluator.go

@@ -0,0 +1,406 @@
+package services
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"sync"
+	"time"
+
+	"golang.org/x/sync/semaphore"
+
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/models"
+	"github.com/kjannette/koin-ping/backend/internal/notifications"
+	"github.com/kjannette/koin-ping/backend/internal/protocols/ethereum"
+	"github.com/kjannette/koin-ping/backend/internal/wei"
+)
+
+const (
+	notificationTimeout    = 30 * time.Second
+	notificationMaxRetries = 3
+	notificationRetryBase  = time.Second
+	maxConcurrentNotifications = 5
+)
+
+type EvaluatorService struct {
+	eth          ethereum.EthereumObserver
+	alertRules   *models.AlertRuleModel
+	alertEvents  *models.AlertEventModel
+	addresses    *models.AddressModel
+	users        *models.UserModel
+	notifConfigs *models.NotificationConfigModel
+	notifSem     *semaphore.Weighted
+	notifWg      sync.WaitGroup
+}
+
+func NewEvaluatorService(
+	eth ethereum.EthereumObserver,
+	alertRules *models.AlertRuleModel,
+	alertEvents *models.AlertEventModel,
+	addresses *models.AddressModel,
+	users *models.UserModel,
+	notifConfigs *models.NotificationConfigModel,
+) *EvaluatorService {
+	return &EvaluatorService{
+		eth:          eth,
+		alertRules:   alertRules,
+		alertEvents:  alertEvents,
+		addresses:    addresses,
+		users:        users,
+		notifConfigs: notifConfigs,
+		notifSem:     semaphore.NewWeighted(maxConcurrentNotifications),
+	}
+}
+
+func (s *EvaluatorService) Evaluate(ctx context.Context, observations []domain.ObservedTx) (int, error) {
+	alertsFired := 0
+
+	for _, obs := range observations {
+		fired, err := s.evaluateObservation(ctx, obs)
+		if err != nil {
+			log.Printf("Error evaluating observation for address ID %d: %v", obs.AddressID, err)
+			continue
+		}
+		alertsFired += fired
+	}
+
+	return alertsFired, nil
+}
+
+func (s *EvaluatorService) evaluateObservation(ctx context.Context, obs domain.ObservedTx) (int, error) {
+	rules, err := s.alertRules.ListByAddress(ctx, obs.AddressID)
+	if err != nil {
+		return 0, err
+	}
+
+	alertsFired := 0
+	for _, rule := range rules {
+		if !rule.Enabled {
+			continue
+		}
+
+		matches, err := s.ruleMatches(ctx, rule, obs)
+		if err != nil {
+			log.Printf("Error matching rule %d: %v", rule.ID, err)
+			continue
+		}
+
+		if matches {
+			if err := s.fireAlert(ctx, rule, obs); err != nil {
+				log.Printf("Error firing alert for rule %d: %v", rule.ID, err)
+				continue
+			}
+			alertsFired++
+		}
+	}
+
+	return alertsFired, nil
+}
+
+func (s *EvaluatorService) ruleMatches(ctx context.Context, rule domain.AlertRule, obs domain.ObservedTx) (bool, error) {
+	switch rule.Type {
+	case domain.AlertIncomingTx:
+		return s.matchesDirectionalTx(rule, obs, domain.DirectionIncoming)
+	case domain.AlertOutgoingTx:
+		return s.matchesDirectionalTx(rule, obs, domain.DirectionOutgoing)
+	case domain.AlertLargeTransfer:
+		return s.matchesLargeTransfer(rule, obs)
+	case domain.AlertBalanceBelow:
+		return s.matchesBalanceBelow(ctx, rule, obs)
+	default:
+		log.Printf("Unknown rule type: %s", rule.Type)
+		return false, nil
+	}
+}
+
+func (s *EvaluatorService) matchesDirectionalTx(rule domain.AlertRule, obs domain.ObservedTx, expected domain.Direction) (bool, error) {
+	if obs.Direction != expected {
+		return false, nil
+	}
+
+	if rule.Minimum != nil {
+		minWei, err := wei.FromEth(*rule.Minimum)
+		if err != nil {
+			return false, err
+		}
+		aboveMin, err := wei.GreaterThanOrEqual(obs.Value, minWei)
+		if err != nil {
+			return false, err
+		}
+		if !aboveMin {
+			return false, nil
+		}
+	}
+
+	if rule.Maximum != nil {
+		maxWei, err := wei.FromEth(*rule.Maximum)
+		if err != nil {
+			return false, err
+		}
+		belowMax, err := wei.LessThanOrEqual(obs.Value, maxWei)
+		if err != nil {
+			return false, err
+		}
+		if !belowMax {
+			return false, nil
+		}
+	}
+
+	return true, nil
+}
+
+func (s *EvaluatorService) matchesLargeTransfer(rule domain.AlertRule, obs domain.ObservedTx) (bool, error) {
+	if rule.Threshold == nil {
+		return false, nil
+	}
+
+	thresholdWei, err := wei.FromEth(*rule.Threshold)
+	if err != nil {
+		return false, err
+	}
+
+	return wei.GreaterThanOrEqual(obs.Value, thresholdWei)
+}
+
+// matchesBalanceBelow only triggers after outgoing transactions, since incoming
+// transactions increase balance and can't cause it to drop below threshold.
+func (s *EvaluatorService) matchesBalanceBelow(ctx context.Context, rule domain.AlertRule, obs domain.ObservedTx) (bool, error) {
+	if rule.Threshold == nil {
+		return false, nil
+	}
+
+	if obs.Direction != domain.DirectionOutgoing {
+		return false, nil
+	}
+
+	addr, err := s.addresses.FindByID(ctx, obs.AddressID, nil)
+	if err != nil {
+		return false, err
+	}
+	if addr == nil {
+		log.Printf("Address ID %d not found", obs.AddressID)
+		return false, nil
+	}
+
+	balanceWei, err := s.eth.GetBalance(ctx, addr.Address)
+	if err != nil {
+		return false, err
+	}
+
+	thresholdWei, err := wei.FromEth(*rule.Threshold)
+	if err != nil {
+		return false, err
+	}
+
+	return wei.LessThan(balanceWei, thresholdWei)
+}
+
+func (s *EvaluatorService) fireAlert(ctx context.Context, rule domain.AlertRule, obs domain.ObservedTx) error {
+	addr, err := s.addresses.FindByID(ctx, obs.AddressID, nil)
+	if err != nil {
+		return err
+	}
+
+	addressLabel := "Unknown"
+	if addr != nil {
+		if addr.Label != nil {
+			addressLabel = *addr.Label
+		} else {
+			addressLabel = addr.Address
+		}
+	}
+
+	message := s.buildMessage(rule, obs)
+	txHash := &obs.Hash
+
+	event, err := s.alertEvents.Create(ctx, rule.ID, message, &addressLabel, txHash)
+	if err != nil {
+		return err
+	}
+
+	if event == nil {
+		log.Printf("[ALERT DEDUP] Rule %d (%s) - duplicate event skipped for TX: %s", rule.ID, rule.Type, obs.Hash)
+		return nil
+	}
+
+	log.Printf("[ALERT FIRED] Rule %d (%s) - %s - TX: %s", rule.ID, rule.Type, message, obs.Hash)
+
+	if addr != nil {
+		userID := addr.UserID
+		address := addr.Address
+		if err := s.notifSem.Acquire(ctx, 1); err != nil {
+			log.Printf("Failed to acquire notification semaphore for rule %d: %v", rule.ID, err)
+			return nil
+		}
+		s.notifWg.Add(1)
+		go func() {
+			defer s.notifSem.Release(1)
+			defer s.notifWg.Done()
+			notifCtx, cancel := context.WithTimeout(context.Background(), notificationTimeout)
+			defer cancel()
+			s.sendNotification(notifCtx, userID, message, obs, addressLabel, rule, address)
+		}()
+	}
+
+	return nil
+}
+
+// WaitForNotifications blocks until all in-flight notification goroutines finish.
+func (s *EvaluatorService) WaitForNotifications() {
+	s.notifWg.Wait()
+}
+
+func (s *EvaluatorService) buildNotifiers(cfg *domain.NotificationConfig, limits domain.TierLimits) []notifications.Notifier {
+	var notifiers []notifications.Notifier
+
+	if limits.ChannelAllowed("discord") &&
+		cfg.DiscordWebhookURL != nil && *cfg.DiscordWebhookURL != "" {
+		notifiers = append(notifiers, &notifications.DiscordNotifier{WebhookURL: *cfg.DiscordWebhookURL})
+	}
+
+	if limits.ChannelAllowed("telegram") &&
+		cfg.TelegramBotToken != nil && *cfg.TelegramBotToken != "" &&
+		cfg.TelegramChatID != nil && *cfg.TelegramChatID != "" {
+		notifiers = append(notifiers, &notifications.TelegramNotifier{
+			BotToken: *cfg.TelegramBotToken,
+			ChatID:   *cfg.TelegramChatID,
+		})
+	}
+
+	if limits.ChannelAllowed("slack") &&
+		cfg.SlackWebhookURL != nil && *cfg.SlackWebhookURL != "" {
+		notifiers = append(notifiers, &notifications.SlackNotifier{WebhookURL: *cfg.SlackWebhookURL})
+	}
+
+	// Email is delivered exclusively via the daily digest service, never real-time.
+
+	return notifiers
+}
+
+func sendWithRetry(ctx context.Context, n notifications.Notifier, message string, meta notifications.AlertMetadata) error {
+	var lastErr error
+	for attempt := range notificationMaxRetries {
+		if attempt > 0 {
+			wait := notificationRetryBase * time.Duration(1<<(attempt-1))
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-time.After(wait):
+			}
+		}
+
+		if err := n.Send(ctx, message, meta); err != nil {
+			lastErr = err
+
+			if notifications.IsPermanent(err) {
+				log.Printf("Permanent notification failure, skipping retries: %v", err)
+				return err
+			}
+
+			log.Printf("Notification attempt %d/%d failed: %v", attempt+1, notificationMaxRetries, err)
+			continue
+		}
+
+		return nil
+	}
+
+	return lastErr
+}
+
+func (s *EvaluatorService) sendNotification(ctx context.Context, userID, message string, obs domain.ObservedTx, addressLabel string, rule domain.AlertRule, address string) {
+	notifConfig, err := s.notifConfigs.GetConfig(ctx, userID)
+	if err != nil {
+		log.Printf("Failed to get notification config: %v", err)
+		return
+	}
+
+	if notifConfig == nil || !notifConfig.NotificationEnabled {
+		return
+	}
+
+	user, err := s.users.GetByID(ctx, userID)
+	if err != nil || user == nil {
+		log.Printf("Failed to load user %s for tier check in notification: %v", userID, err)
+		return
+	}
+	limits := domain.GetTierLimits(user.SubscriptionTier)
+
+	meta := notifications.AlertMetadata{
+		TxHash:       obs.Hash,
+		AddressLabel: addressLabel,
+		AlertType:    string(rule.Type),
+		Address:      address,
+	}
+
+	for _, n := range s.buildNotifiers(notifConfig, limits) {
+		if err := sendWithRetry(ctx, n, message, meta); err != nil {
+			log.Printf("Notification channel failed for user %s after retries: %v", userID, err)
+		} else {
+			log.Printf("Notification sent to user %s via %T", userID, n)
+		}
+	}
+}
+
+func (s *EvaluatorService) buildMessage(rule domain.AlertRule, obs domain.ObservedTx) string {
+	if obs.IsTokenTransfer() {
+		return s.buildTokenMessage(rule, obs)
+	}
+
+	switch rule.Type {
+	case domain.AlertIncomingTx:
+		ethStr, _ := wei.FormatAsEth(obs.Value, 4)
+		return fmt.Sprintf("Incoming transaction: %s received", ethStr)
+	case domain.AlertOutgoingTx:
+		ethStr, _ := wei.FormatAsEth(obs.Value, 4)
+		return fmt.Sprintf("Outgoing transaction: %s sent", ethStr)
+	case domain.AlertLargeTransfer:
+		ethStr, _ := wei.FormatAsEth(obs.Value, 4)
+		threshold := float64(0)
+		if rule.Threshold != nil {
+			threshold = *rule.Threshold
+		}
+		return fmt.Sprintf("Large transfer detected: %s (threshold: %g ETH)", ethStr, threshold)
+	case domain.AlertBalanceBelow:
+		threshold := float64(0)
+		if rule.Threshold != nil {
+			threshold = *rule.Threshold
+		}
+		return fmt.Sprintf("Balance dropped below threshold of %g ETH", threshold)
+	default:
+		return "Alert triggered"
+	}
+}
+
+const defaultTokenDecimals = 18
+
+func (s *EvaluatorService) buildTokenMessage(rule domain.AlertRule, obs domain.ObservedTx) string {
+	symbol := "tokens"
+	if obs.TokenSymbol != nil {
+		symbol = *obs.TokenSymbol
+	}
+
+	amount := "unknown"
+	if obs.TokenValue != nil {
+		decimals := defaultTokenDecimals
+		if obs.TokenDecimals != nil {
+			decimals = *obs.TokenDecimals
+		}
+		amount = wei.FormatTokenAmount(*obs.TokenValue, decimals)
+	}
+
+	switch rule.Type {
+	case domain.AlertIncomingTx:
+		return fmt.Sprintf("Incoming transfer: %s %s received", amount, symbol)
+	case domain.AlertOutgoingTx:
+		return fmt.Sprintf("Outgoing transfer: %s %s sent", amount, symbol)
+	case domain.AlertLargeTransfer:
+		threshold := float64(0)
+		if rule.Threshold != nil {
+			threshold = *rule.Threshold
+		}
+		return fmt.Sprintf("Large token transfer: %s %s (threshold: %g)", amount, symbol, threshold)
+	default:
+		return fmt.Sprintf("Token transfer: %s %s", amount, symbol)
+	}
+}

backend/internal/services/observer.go

@@ -5,9 +5,9 @@ import (
 	"log"
 	"strings"
 
-	"github.com/kjannette/koin-ping/backend-go/internal/domain"
-	"github.com/kjannette/koin-ping/backend-go/internal/models"
-	"github.com/kjannette/koin-ping/backend-go/internal/protocols/ethereum"
+	"github.com/kjannette/koin-ping/backend/internal/domain"
+	"github.com/kjannette/koin-ping/backend/internal/models"
+	"github.com/kjannette/koin-ping/backend/internal/protocols/ethereum"
 )
 
 const maxBlocksPerRun = 100
@@ -80,6 +80,15 @@ func (s *ObserverService) observeAddress(ctx context.Context, addr domain.Addres
 		}
 	}
 
+	tokenTxs, err := s.eth.GetTokenTransfers(ctx, startBlock, endBlock, addr.Address)
+	if err != nil {
+		log.Printf("Error fetching token transfers for %s: %v", addr.Address, err)
+	} else {
+		for _, tx := range tokenTxs {
+			observations = append(observations, createObservedTx(tx, addr))
+		}
+	}
+
 	if _, err := s.checkpoint.UpdateLastCheckedBlock(ctx, addr.ID, endBlock); err != nil {
 		return nil, err
 	}

backend/internal/wei/converter.go

@@ -90,6 +90,14 @@ func LessThan(weiA, weiB string) (bool, error) {
 	return cmp < 0, nil
 }
 
+func LessThanOrEqual(weiA, weiB string) (bool, error) {
+	cmp, err := Compare(weiA, weiB)
+	if err != nil {
+		return false, err
+	}
+	return cmp <= 0, nil
+}
+
 // FormatAsEth formats a Wei string as "X.XXXX ETH".
 func FormatAsEth(weiString string, decimals int) (string, error) {
 	eth, err := ToEth(weiString)
@@ -98,3 +106,54 @@ func FormatAsEth(weiString string, decimals int) (string, error) {
 	}
 	return fmt.Sprintf("%.*f ETH", decimals, eth), nil
 }
+
+// FormatTokenAmount formats a raw token amount using the token's decimal places.
+// For example, 1000000 USDT (6 decimals) becomes "1".
+func FormatTokenAmount(rawValue string, tokenDecimals int) string {
+	if rawValue == "" || rawValue == "0" {
+		return "0"
+	}
+
+	n, ok := new(big.Int).SetString(rawValue, 10)
+	if !ok {
+		return "0"
+	}
+
+	divisor := new(big.Int).Exp(big.NewInt(10), big.NewInt(int64(tokenDecimals)), nil) //nolint:mnd
+	whole := new(big.Int).Div(n, divisor)
+	remainder := new(big.Int).Mod(n, divisor)
+
+	if remainder.Sign() == 0 {
+		return addThousandsSeparators(whole.String())
+	}
+
+	fracStr := fmt.Sprintf("%0*s", tokenDecimals, remainder.String())
+	fracStr = strings.TrimRight(fracStr, "0")
+	const maxDisplayDecimals = 4
+	if len(fracStr) > maxDisplayDecimals {
+		fracStr = fracStr[:maxDisplayDecimals]
+	}
+
+	return addThousandsSeparators(whole.String()) + "." + fracStr
+}
+
+func addThousandsSeparators(s string) string {
+	if len(s) <= 3 { //nolint:mnd
+		return s
+	}
+
+	var result strings.Builder
+	offset := len(s) % 3 //nolint:mnd
+	if offset > 0 {
+		result.WriteString(s[:offset])
+	}
+
+	for i := offset; i < len(s); i += 3 { //nolint:mnd
+		if result.Len() > 0 {
+			result.WriteByte(',')
+		}
+		result.WriteString(s[i : i+3]) //nolint:mnd
+	}
+
+	return result.String()
+}

frontend/package-lock.json

@@ -12,7 +12,7 @@
                 "firebase": "^12.7.0",
                 "react": "^19.2.3",
                 "react-dom": "^19.2.3",
-                "react-router-dom": "^7.11.0"
+                "react-router-dom": "^7.12.0"
             },
             "devDependencies": {
                 "@types/react": "^19.2.7",
@@ -20,7 +20,7 @@
                 "@vitejs/plugin-react": "^5.1.2",
                 "prettier": "^3.8.1",
                 "typescript": "^5.9.3",
-                "vite": "^7.3.0"
+                "vite": "^7.3.2"
             }
         },
         "node_modules/@babel/code-frame": {
@@ -1513,9 +1513,9 @@
             "license": "MIT"
         },
         "node_modules/@rollup/rollup-android-arm-eabi": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.54.0.tgz",
-            "integrity": "sha512-OywsdRHrFvCdvsewAInDKCNyR3laPA2mc9bRYJ6LBp5IyvF3fvXbbNR0bSzHlZVFtn6E0xw2oZlyjg4rKCVcng==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.59.0.tgz",
+            "integrity": "sha512-upnNBkA6ZH2VKGcBj9Fyl9IGNPULcjXRlg0LLeaioQWueH30p6IXtJEbKAgvyv+mJaMxSm1l6xwDXYjpEMiLMg==",
             "cpu": [
                 "arm"
             ],
@@ -1527,9 +1527,9 @@
             ]
         },
         "node_modules/@rollup/rollup-android-arm64": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.54.0.tgz",
-            "integrity": "sha512-Skx39Uv+u7H224Af+bDgNinitlmHyQX1K/atIA32JP3JQw6hVODX5tkbi2zof/E69M1qH2UoN3Xdxgs90mmNYw==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.59.0.tgz",
+            "integrity": "sha512-hZ+Zxj3SySm4A/DylsDKZAeVg0mvi++0PYVceVyX7hemkw7OreKdCvW2oQ3T1FMZvCaQXqOTHb8qmBShoqk69Q==",
             "cpu": [
                 "arm64"
             ],
@@ -1541,9 +1541,9 @@
             ]
         },
         "node_modules/@rollup/rollup-darwin-arm64": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.54.0.tgz",
-            "integrity": "sha512-k43D4qta/+6Fq+nCDhhv9yP2HdeKeP56QrUUTW7E6PhZP1US6NDqpJj4MY0jBHlJivVJD5P8NxrjuobZBJTCRw==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.59.0.tgz",
+            "integrity": "sha512-W2Psnbh1J8ZJw0xKAd8zdNgF9HRLkdWwwdWqubSVk0pUuQkoHnv7rx4GiF9rT4t5DIZGAsConRE3AxCdJ4m8rg==",
             "cpu": [
                 "arm64"
             ],
@@ -1555,9 +1555,9 @@
             ]
         },
         "node_modules/@rollup/rollup-darwin-x64": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.54.0.tgz",
-            "integrity": "sha512-cOo7biqwkpawslEfox5Vs8/qj83M/aZCSSNIWpVzfU2CYHa2G3P1UN5WF01RdTHSgCkri7XOlTdtk17BezlV3A==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.59.0.tgz",
+            "integrity": "sha512-ZW2KkwlS4lwTv7ZVsYDiARfFCnSGhzYPdiOU4IM2fDbL+QGlyAbjgSFuqNRbSthybLbIJ915UtZBtmuLrQAT/w==",
             "cpu": [
                 "x64"
             ],
@@ -1569,9 +1569,9 @@
             ]
         },
         "node_modules/@rollup/rollup-freebsd-arm64": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.54.0.tgz",
-            "integrity": "sha512-miSvuFkmvFbgJ1BevMa4CPCFt5MPGw094knM64W9I0giUIMMmRYcGW/JWZDriaw/k1kOBtsWh1z6nIFV1vPNtA==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.59.0.tgz",
+            "integrity": "sha512-EsKaJ5ytAu9jI3lonzn3BgG8iRBjV4LxZexygcQbpiU0wU0ATxhNVEpXKfUa0pS05gTcSDMKpn3Sx+QB9RlTTA==",
             "cpu": [
                 "arm64"
             ],
@@ -1583,9 +1583,9 @@
             ]
         },
         "node_modules/@rollup/rollup-freebsd-x64": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.54.0.tgz",
-            "integrity": "sha512-KGXIs55+b/ZfZsq9aR026tmr/+7tq6VG6MsnrvF4H8VhwflTIuYh+LFUlIsRdQSgrgmtM3fVATzEAj4hBQlaqQ==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.59.0.tgz",
+            "integrity": "sha512-d3DuZi2KzTMjImrxoHIAODUZYoUUMsuUiY4SRRcJy6NJoZ6iIqWnJu9IScV9jXysyGMVuW+KNzZvBLOcpdl3Vg==",
             "cpu": [
                 "x64"
             ],
@@ -1597,9 +1597,9 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.54.0.tgz",
-            "integrity": "sha512-EHMUcDwhtdRGlXZsGSIuXSYwD5kOT9NVnx9sqzYiwAc91wfYOE1g1djOEDseZJKKqtHAHGwnGPQu3kytmfaXLQ==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.59.0.tgz",
+            "integrity": "sha512-t4ONHboXi/3E0rT6OZl1pKbl2Vgxf9vJfWgmUoCEVQVxhW6Cw/c8I6hbbu7DAvgp82RKiH7TpLwxnJeKv2pbsw==",
             "cpu": [
                 "arm"
             ],
@@ -1611,9 +1611,9 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-arm-musleabihf": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.54.0.tgz",
-            "integrity": "sha512-+pBrqEjaakN2ySv5RVrj/qLytYhPKEUwk+e3SFU5jTLHIcAtqh2rLrd/OkbNuHJpsBgxsD8ccJt5ga/SeG0JmA==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.59.0.tgz",
+            "integrity": "sha512-CikFT7aYPA2ufMD086cVORBYGHffBo4K8MQ4uPS/ZnY54GKj36i196u8U+aDVT2LX4eSMbyHtyOh7D7Zvk2VvA==",
             "cpu": [
                 "arm"
             ],
@@ -1625,9 +1625,9 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-arm64-gnu": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.54.0.tgz",
-            "integrity": "sha512-NSqc7rE9wuUaRBsBp5ckQ5CVz5aIRKCwsoa6WMF7G01sX3/qHUw/z4pv+D+ahL1EIKy6Enpcnz1RY8pf7bjwng==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.59.0.tgz",
+            "integrity": "sha512-jYgUGk5aLd1nUb1CtQ8E+t5JhLc9x5WdBKew9ZgAXg7DBk0ZHErLHdXM24rfX+bKrFe+Xp5YuJo54I5HFjGDAA==",
             "cpu": [
                 "arm64"
             ],
@@ -1639,9 +1639,9 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-arm64-musl": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.54.0.tgz",
-            "integrity": "sha512-gr5vDbg3Bakga5kbdpqx81m2n9IX8M6gIMlQQIXiLTNeQW6CucvuInJ91EuCJ/JYvc+rcLLsDFcfAD1K7fMofg==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.59.0.tgz",
+            "integrity": "sha512-peZRVEdnFWZ5Bh2KeumKG9ty7aCXzzEsHShOZEFiCQlDEepP1dpUl/SrUNXNg13UmZl+gzVDPsiCwnV1uI0RUA==",
             "cpu": [
                 "arm64"
             ],
@@ -1653,9 +1653,23 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-loong64-gnu": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.54.0.tgz",
-            "integrity": "sha512-gsrtB1NA3ZYj2vq0Rzkylo9ylCtW/PhpLEivlgWe0bpgtX5+9j9EZa0wtZiCjgu6zmSeZWyI/e2YRX1URozpIw==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.59.0.tgz",
+            "integrity": "sha512-gbUSW/97f7+r4gHy3Jlup8zDG190AuodsWnNiXErp9mT90iCy9NKKU0Xwx5k8VlRAIV2uU9CsMnEFg/xXaOfXg==",
+            "cpu": [
+                "loong64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ]
+        },
+        "node_modules/@rollup/rollup-linux-loong64-musl": {
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.59.0.tgz",
+            "integrity": "sha512-yTRONe79E+o0FWFijasoTjtzG9EBedFXJMl888NBEDCDV9I2wGbFFfJQQe63OijbFCUZqxpHz1GzpbtSFikJ4Q==",
             "cpu": [
                 "loong64"
             ],
@@ -1667,9 +1681,23 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-ppc64-gnu": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.54.0.tgz",
-            "integrity": "sha512-y3qNOfTBStmFNq+t4s7Tmc9hW2ENtPg8FeUD/VShI7rKxNW7O4fFeaYbMsd3tpFlIg1Q8IapFgy7Q9i2BqeBvA==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.59.0.tgz",
+            "integrity": "sha512-sw1o3tfyk12k3OEpRddF68a1unZ5VCN7zoTNtSn2KndUE+ea3m3ROOKRCZxEpmT9nsGnogpFP9x6mnLTCaoLkA==",
+            "cpu": [
+                "ppc64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ]
+        },
+        "node_modules/@rollup/rollup-linux-ppc64-musl": {
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.59.0.tgz",
+            "integrity": "sha512-+2kLtQ4xT3AiIxkzFVFXfsmlZiG5FXYW7ZyIIvGA7Bdeuh9Z0aN4hVyXS/G1E9bTP/vqszNIN/pUKCk/BTHsKA==",
             "cpu": [
                 "ppc64"
             ],
@@ -1681,9 +1709,9 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-riscv64-gnu": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.54.0.tgz",
-            "integrity": "sha512-89sepv7h2lIVPsFma8iwmccN7Yjjtgz0Rj/Ou6fEqg3HDhpCa+Et+YSufy27i6b0Wav69Qv4WBNl3Rs6pwhebQ==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.59.0.tgz",
+            "integrity": "sha512-NDYMpsXYJJaj+I7UdwIuHHNxXZ/b/N2hR15NyH3m2qAtb/hHPA4g4SuuvrdxetTdndfj9b1WOmy73kcPRoERUg==",
             "cpu": [
                 "riscv64"
             ],
@@ -1695,9 +1723,9 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-riscv64-musl": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.54.0.tgz",
-            "integrity": "sha512-ZcU77ieh0M2Q8Ur7D5X7KvK+UxbXeDHwiOt/CPSBTI1fBmeDMivW0dPkdqkT4rOgDjrDDBUed9x4EgraIKoR2A==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.59.0.tgz",
+            "integrity": "sha512-nLckB8WOqHIf1bhymk+oHxvM9D3tyPndZH8i8+35p/1YiVoVswPid2yLzgX7ZJP0KQvnkhM4H6QZ5m0LzbyIAg==",
             "cpu": [
                 "riscv64"
             ],
@@ -1709,9 +1737,9 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-s390x-gnu": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.54.0.tgz",
-            "integrity": "sha512-2AdWy5RdDF5+4YfG/YesGDDtbyJlC9LHmL6rZw6FurBJ5n4vFGupsOBGfwMRjBYH7qRQowT8D/U4LoSvVwOhSQ==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.59.0.tgz",
+            "integrity": "sha512-oF87Ie3uAIvORFBpwnCvUzdeYUqi2wY6jRFWJAy1qus/udHFYIkplYRW+wo+GRUP4sKzYdmE1Y3+rY5Gc4ZO+w==",
             "cpu": [
                 "s390x"
             ],
@@ -1723,9 +1751,9 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-x64-gnu": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.54.0.tgz",
-            "integrity": "sha512-WGt5J8Ij/rvyqpFexxk3ffKqqbLf9AqrTBbWDk7ApGUzaIs6V+s2s84kAxklFwmMF/vBNGrVdYgbblCOFFezMQ==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.59.0.tgz",
+            "integrity": "sha512-3AHmtQq/ppNuUspKAlvA8HtLybkDflkMuLK4DPo77DfthRb71V84/c4MlWJXixZz4uruIH4uaa07IqoAkG64fg==",
             "cpu": [
                 "x64"
             ],
@@ -1737,9 +1765,9 @@
             ]
         },
         "node_modules/@rollup/rollup-linux-x64-musl": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.54.0.tgz",
-            "integrity": "sha512-JzQmb38ATzHjxlPHuTH6tE7ojnMKM2kYNzt44LO/jJi8BpceEC8QuXYA908n8r3CNuG/B3BV8VR3Hi1rYtmPiw==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.59.0.tgz",
+            "integrity": "sha512-2UdiwS/9cTAx7qIUZB/fWtToJwvt0Vbo0zmnYt7ED35KPg13Q0ym1g442THLC7VyI6JfYTP4PiSOWyoMdV2/xg==",
             "cpu": [
                 "x64"
             ],
@@ -1750,10 +1778,24 @@
                 "linux"
             ]
         },
+        "node_modules/@rollup/rollup-openbsd-x64": {
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.59.0.tgz",
+            "integrity": "sha512-M3bLRAVk6GOwFlPTIxVBSYKUaqfLrn8l0psKinkCFxl4lQvOSz8ZrKDz2gxcBwHFpci0B6rttydI4IpS4IS/jQ==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "openbsd"
+            ]
+        },
         "node_modules/@rollup/rollup-openharmony-arm64": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.54.0.tgz",
-            "integrity": "sha512-huT3fd0iC7jigGh7n3q/+lfPcXxBi+om/Rs3yiFxjvSxbSB6aohDFXbWvlspaqjeOh+hx7DDHS+5Es5qRkWkZg==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.59.0.tgz",
+            "integrity": "sha512-tt9KBJqaqp5i5HUZzoafHZX8b5Q2Fe7UjYERADll83O4fGqJ49O1FsL6LpdzVFQcpwvnyd0i+K/VSwu/o/nWlA==",
             "cpu": [
                 "arm64"
             ],
@@ -1765,9 +1807,9 @@
             ]
         },
         "node_modules/@rollup/rollup-win32-arm64-msvc": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.54.0.tgz",
-            "integrity": "sha512-c2V0W1bsKIKfbLMBu/WGBz6Yci8nJ/ZJdheE0EwB73N3MvHYKiKGs3mVilX4Gs70eGeDaMqEob25Tw2Gb9Nqyw==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.59.0.tgz",
+            "integrity": "sha512-V5B6mG7OrGTwnxaNUzZTDTjDS7F75PO1ae6MJYdiMu60sq0CqN5CVeVsbhPxalupvTX8gXVSU9gq+Rx1/hvu6A==",
             "cpu": [
                 "arm64"
             ],
@@ -1779,9 +1821,9 @@
             ]
         },
         "node_modules/@rollup/rollup-win32-ia32-msvc": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.54.0.tgz",
-            "integrity": "sha512-woEHgqQqDCkAzrDhvDipnSirm5vxUXtSKDYTVpZG3nUdW/VVB5VdCYA2iReSj/u3yCZzXID4kuKG7OynPnB3WQ==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.59.0.tgz",
+            "integrity": "sha512-UKFMHPuM9R0iBegwzKF4y0C4J9u8C6MEJgFuXTBerMk7EJ92GFVFYBfOZaSGLu6COf7FxpQNqhNS4c4icUPqxA==",
             "cpu": [
                 "ia32"
             ],
@@ -1793,9 +1835,9 @@
             ]
         },
         "node_modules/@rollup/rollup-win32-x64-gnu": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.54.0.tgz",
-            "integrity": "sha512-dzAc53LOuFvHwbCEOS0rPbXp6SIhAf2txMP5p6mGyOXXw5mWY8NGGbPMPrs4P1WItkfApDathBj/NzMLUZ9rtQ==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.59.0.tgz",
+            "integrity": "sha512-laBkYlSS1n2L8fSo1thDNGrCTQMmxjYY5G0WFWjFFYZkKPjsMBsgJfGf4TLxXrF6RyhI60L8TMOjBMvXiTcxeA==",
             "cpu": [
                 "x64"
             ],
@@ -1807,9 +1849,9 @@
             ]
         },
         "node_modules/@rollup/rollup-win32-x64-msvc": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.54.0.tgz",
-            "integrity": "sha512-hYT5d3YNdSh3mbCU1gwQyPgQd3T2ne0A3KG8KSBdav5TiBg6eInVmV+TeR5uHufiIgSFg0XsOWGW5/RhNcSvPg==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.59.0.tgz",
+            "integrity": "sha512-2HRCml6OztYXyJXAvdDXPKcawukWY2GpR5/nxKp4iBgiO3wcoEGkAaqctIbZcNB6KlUQBIqt8VYkNSj2397EfA==",
             "cpu": [
                 "x64"
             ],
@@ -2385,9 +2427,9 @@
             }
         },
         "node_modules/postcss": {
-            "version": "8.5.6",
-            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz",
-            "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==",
+            "version": "8.5.10",
+            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz",
+            "integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
             "dev": true,
             "funding": [
                 {
@@ -2430,10 +2472,9 @@
             }
         },
         "node_modules/protobufjs": {
-            "version": "7.5.4",
-            "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.4.tgz",
-            "integrity": "sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg==",
-            "hasInstallScript": true,
+            "version": "7.5.5",
+            "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.5.tgz",
+            "integrity": "sha512-3wY1AxV+VBNW8Yypfd1yQY9pXnqTAN+KwQxL8iYm3/BjKYMNg4i0owhEe26PWDOMaIrzeeF98Lqd5NGz4omiIg==",
             "license": "BSD-3-Clause",
             "dependencies": {
                 "@protobufjs/aspromise": "^1.1.2",
@@ -2487,9 +2528,9 @@
             }
         },
         "node_modules/react-router": {
-            "version": "7.11.0",
-            "resolved": "https://registry.npmjs.org/react-router/-/react-router-7.11.0.tgz",
-            "integrity": "sha512-uI4JkMmjbWCZc01WVP2cH7ZfSzH91JAZUDd7/nIprDgWxBV1TkkmLToFh7EbMTcMak8URFRa2YoBL/W8GWnCTQ==",
+            "version": "7.12.0",
+            "resolved": "https://registry.npmjs.org/react-router/-/react-router-7.12.0.tgz",
+            "integrity": "sha512-kTPDYPFzDVGIIGNLS5VJykK0HfHLY5MF3b+xj0/tTyNYL1gF1qs7u67Z9jEhQk2sQ98SUaHxlG31g1JtF7IfVw==",
             "license": "MIT",
             "dependencies": {
                 "cookie": "^1.0.1",
@@ -2509,12 +2550,12 @@
             }
         },
         "node_modules/react-router-dom": {
-            "version": "7.11.0",
-            "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-7.11.0.tgz",
-            "integrity": "sha512-e49Ir/kMGRzFOOrYQBdoitq3ULigw4lKbAyKusnvtDu2t4dBX4AGYPrzNvorXmVuOyeakai6FUPW5MmibvVG8g==",
+            "version": "7.12.0",
+            "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-7.12.0.tgz",
+            "integrity": "sha512-pfO9fiBcpEfX4Tx+iTYKDtPbrSLLCbwJ5EqP+SPYQu1VYCXdy79GSj0wttR0U4cikVdlImZuEZ/9ZNCgoaxwBA==",
             "license": "MIT",
             "dependencies": {
-                "react-router": "7.11.0"
+                "react-router": "7.12.0"
             },
             "engines": {
                 "node": ">=20.0.0"
@@ -2534,9 +2575,9 @@
             }
         },
         "node_modules/rollup": {
-            "version": "4.54.0",
-            "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.54.0.tgz",
-            "integrity": "sha512-3nk8Y3a9Ea8szgKhinMlGMhGMw89mqule3KWczxhIzqudyHdCIOHw8WJlj/r329fACjKLEh13ZSk7oE22kyeIw==",
+            "version": "4.59.0",
+            "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.59.0.tgz",
+            "integrity": "sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
@@ -2550,28 +2591,31 @@
                 "npm": ">=8.0.0"
             },
             "optionalDependencies": {
-                "@rollup/rollup-android-arm-eabi": "4.54.0",
-                "@rollup/rollup-android-arm64": "4.54.0",
-                "@rollup/rollup-darwin-arm64": "4.54.0",
-                "@rollup/rollup-darwin-x64": "4.54.0",
-                "@rollup/rollup-freebsd-arm64": "4.54.0",
-                "@rollup/rollup-freebsd-x64": "4.54.0",
-                "@rollup/rollup-linux-arm-gnueabihf": "4.54.0",
-                "@rollup/rollup-linux-arm-musleabihf": "4.54.0",
-                "@rollup/rollup-linux-arm64-gnu": "4.54.0",
-                "@rollup/rollup-linux-arm64-musl": "4.54.0",
-                "@rollup/rollup-linux-loong64-gnu": "4.54.0",
-                "@rollup/rollup-linux-ppc64-gnu": "4.54.0",
-                "@rollup/rollup-linux-riscv64-gnu": "4.54.0",
-                "@rollup/rollup-linux-riscv64-musl": "4.54.0",
-                "@rollup/rollup-linux-s390x-gnu": "4.54.0",
-                "@rollup/rollup-linux-x64-gnu": "4.54.0",
-                "@rollup/rollup-linux-x64-musl": "4.54.0",
-                "@rollup/rollup-openharmony-arm64": "4.54.0",
-                "@rollup/rollup-win32-arm64-msvc": "4.54.0",
-                "@rollup/rollup-win32-ia32-msvc": "4.54.0",
-                "@rollup/rollup-win32-x64-gnu": "4.54.0",
-                "@rollup/rollup-win32-x64-msvc": "4.54.0",
+                "@rollup/rollup-android-arm-eabi": "4.59.0",
+                "@rollup/rollup-android-arm64": "4.59.0",
+                "@rollup/rollup-darwin-arm64": "4.59.0",
+                "@rollup/rollup-darwin-x64": "4.59.0",
+                "@rollup/rollup-freebsd-arm64": "4.59.0",
+                "@rollup/rollup-freebsd-x64": "4.59.0",
+                "@rollup/rollup-linux-arm-gnueabihf": "4.59.0",
+                "@rollup/rollup-linux-arm-musleabihf": "4.59.0",
+                "@rollup/rollup-linux-arm64-gnu": "4.59.0",
+                "@rollup/rollup-linux-arm64-musl": "4.59.0",
+                "@rollup/rollup-linux-loong64-gnu": "4.59.0",
+                "@rollup/rollup-linux-loong64-musl": "4.59.0",
+                "@rollup/rollup-linux-ppc64-gnu": "4.59.0",
+                "@rollup/rollup-linux-ppc64-musl": "4.59.0",
+                "@rollup/rollup-linux-riscv64-gnu": "4.59.0",
+                "@rollup/rollup-linux-riscv64-musl": "4.59.0",
+                "@rollup/rollup-linux-s390x-gnu": "4.59.0",
+                "@rollup/rollup-linux-x64-gnu": "4.59.0",
+                "@rollup/rollup-linux-x64-musl": "4.59.0",
+                "@rollup/rollup-openbsd-x64": "4.59.0",
+                "@rollup/rollup-openharmony-arm64": "4.59.0",
+                "@rollup/rollup-win32-arm64-msvc": "4.59.0",
+                "@rollup/rollup-win32-ia32-msvc": "4.59.0",
+                "@rollup/rollup-win32-x64-gnu": "4.59.0",
+                "@rollup/rollup-win32-x64-msvc": "4.59.0",
                 "fsevents": "~2.3.2"
             }
         },
@@ -2728,9 +2772,9 @@
             }
         },
         "node_modules/vite": {
-            "version": "7.3.0",
-            "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.0.tgz",
-            "integrity": "sha512-dZwN5L1VlUBewiP6H9s2+B3e3Jg96D0vzN+Ry73sOefebhYr9f94wwkMNN/9ouoU8pV1BqA1d1zGk8928cx0rg==",
+            "version": "7.3.2",
+            "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.2.tgz",
+            "integrity": "sha512-Bby3NOsna2jsjfLVOHKes8sGwgl4TT0E6vvpYgnAYDIF/tie7MRaFthmKuHx1NSXjiTueXH3do80FMQgvEktRg==",
             "dev": true,
             "license": "MIT",
             "peer": true,

frontend/package.json

@@ -23,7 +23,7 @@
         "firebase": "^12.7.0",
         "react": "^19.2.3",
         "react-dom": "^19.2.3",
-        "react-router-dom": "^7.11.0"
+        "react-router-dom": "^7.12.0"
     },
     "devDependencies": {
         "@types/react": "^19.2.7",
@@ -31,6 +31,6 @@
         "@vitejs/plugin-react": "^5.1.2",
         "prettier": "^3.8.1",
         "typescript": "^5.9.3",
-        "vite": "^7.3.0"
+        "vite": "^7.3.2"
     }
 }

frontend/src/App.jsx

@@ -1,77 +1,72 @@
-import { Routes, Route, Link, Navigate } from "react-router-dom";
+import { Routes, Route, Navigate } from "react-router-dom";
 import { useAuth } from "./contexts/AuthContext";
-import Login from "./pages/Login";
+import Navbar from "./components/Navbar";
+import Footer from "./components/Footer";
+import Login from "./pages/login/Login";
 import Signup from "./pages/Signup";
-import Addresses from "./pages/Addresses";
-import Alerts from "./pages/Alerts";
-import AlertHistory from "./pages/AlertHistory";
+import Subscribe from "./pages/subscribe/Subscribe";
+import CheckoutReturn from "./pages/subscribe/CheckoutReturn";
+import Addresses from "./pages/addresses/Addresses";
+import Alerts from "./pages/alerts/Alerts";
+import AlertHistory from "./pages/alertHistory/AlertHistory";
+import Account from "./pages/user_account/Account";
+import Terms from "./pages/terms/Terms";
+import Privacy from "./pages/privacy/Privacy";
+import Support from "./pages/support/Support";
 
 export default function App() {
-    const { currentUser, logout } = useAuth();
+  const { currentUser, isSubscribed } = useAuth();
 
-    // Show login/signup routes if not authenticated
   if (!currentUser) {
     return (
       <Routes>
         <Route path="/login" element={<Login />} />
         <Route path="/signup" element={<Signup />} />
+        <Route path="/subscribe" element={<Subscribe />} />
+        <Route path="/subscribe/return/:sessionId" element={<CheckoutReturn />} />
         <Route path="*" element={<Navigate to="/login" />} />
       </Routes>
     );
   }
 
-    // Show main app if authenticated
+  if (!isSubscribed) {
     return (
-        <div style={{ padding: "1rem" }}>
-            <nav
-                style={{
-                    marginBottom: "1rem",
-                    display: "flex",
-                    justifyContent: "space-between",
-                    alignItems: "center",
-                }}
-            >
-                <div>
-                    <Link to="/addresses">Addresses</Link>
-                    {" | "}
-                    <Link to="/alerts">Alerts</Link>
-                    {" | "}
-                    <Link to="/history">History</Link>
+      <div className="app-layout">
+        <div className="app-layout__main">
+          <Routes>
+            <Route path="/subscribe" element={<Subscribe />} />
+            <Route path="/subscribe/return/:sessionId" element={<CheckoutReturn />} />
+            <Route path="/account" element={<><Navbar /><Account /></>} />
+            <Route path="/terms" element={<><Navbar /><Terms /></>} />
+            <Route path="/privacy" element={<><Navbar /><Privacy /></>} />
+            <Route path="/support" element={<><Navbar /><Support /></>} />
+            <Route path="*" element={<Navigate to="/subscribe" />} />
+          </Routes>
         </div>
-                <div
-                    style={{
-                        display: "flex",
-                        alignItems: "center",
-                        gap: "1rem",
-                    }}
-                >
-                    <span style={{ fontSize: "0.9rem", color: "#999" }}>
-                        {currentUser.email}
-                    </span>
-                    <button
-                        onClick={logout}
-                        style={{
-                            padding: "0.5rem 1rem",
-                            fontSize: "0.9rem",
-                            backgroundColor: "#333",
-                            color: "white",
-                            border: "1px solid #555",
-                            borderRadius: "4px",
-                            cursor: "pointer",
-                        }}
-                    >
-                        Logout
-                    </button>
+        <Footer />
       </div>
-            </nav>
+    );
+  }
 
+  return (
+    <div className="app-layout">
+      <Navbar />
+      <div className="app-layout__main">
         <Routes>
           <Route path="/" element={<Addresses />} />
           <Route path="/addresses" element={<Addresses />} />
           <Route path="/alerts" element={<Alerts />} />
-                <Route path="/history" element={<AlertHistory />} />
+          <Route path="/alertevents" element={<AlertHistory />} />
+          <Route path="/account" element={<Account />} />
+          <Route path="/subscribe" element={<Subscribe />} />
+          <Route path="/subscribe/return/:sessionId" element={<CheckoutReturn />} />
+          <Route path="/terms" element={<Terms />} />
+          <Route path="/privacy" element={<Privacy />} />
+          <Route path="/support" element={<Support />} />
           <Route path="*" element={<Navigate to="/addresses" />} />
         </Routes>
       </div>
+      <Footer />
+    </div>
   );
 }