@monadiam/notification-service

Platform | Notifications: email via AWS SES, SMS via AWS SNS, in-app notifications, recipient preferences, dispatch retries and message status tracking.

---

Local Code Graph (Graphify)

Install once with uv, then open a new terminal:

uv tool install graphifyy==0.9.65
uv tool update-shell

Run make graphify from the repository root to create or update the local code graph and report. No API key is required. Outputs in graphify-out/ are ignored by Git. Agent guidance: AGENTS.md.

---

Local TypeScript Navigation (LSP-MCP)

lsmcp and TypeScript Language Server are pinned dev dependencies. Install with pnpm install using the Node version from package.json. Run make lsp from the repository root to start the stdio MCP server; an MCP client must connect to it to issue queries.

For an MCP client, use command node, arguments ["node_modules/@mizchi/lsmcp/dist/lsmcp.js", "--config", ".lsmcp/config.json"], and set its working directory to this repository. Desktop clients may need an absolute Node executable path. Configuration: .lsmcp/config.json. Local indexes and caches are ignored by Git. Agent guidance: AGENTS.md.

Known limitation in lsmcp 0.10.0: definition previews can be empty for encoded pnpm dependency paths. Hover still works; resolve_symbol locates the installed package entry point. See AGENTS.md for the fallback.

---

Local Deployment

1. Start the infra repository first.

2. Start identity-service and access-control-service when authenticated/authorized flows are required.

3. Create the local env file:

make env

4. Build and start the service:

make build
make up

The local service container depends on:

Dependency	Address inside Docker network
PostgreSQL	notification-postgresql:5432
Redis	notification-redis:6379
Kafka	kafka:29092
Vault	vault:8200
Identity JWKS	identity-service-app:4002
Access Control gRPC	access-control-service-app:50051

Shared Docker networks are created by the infra repository: postgres-net, redis-net, kafka-net, and vault-net.

---

Stand Configuration

Runtime settings: .env.stand.example.

Connection	Stand mode	Mounted files / credentials
PostgreSQL	CNPG rw / ro, TLS, password	/tls/postgresql/ca.crt; POSTGRES_USER, POSTGRES_PASSWORD
Redis	Sentinel, master discovery, mTLS	/tls/redis/{ca.crt,tls.crt,tls.key}; REDIS_PASSWORD
Kafka	TLS + SCRAM-SHA-512	/tls/kafka/ca.crt; /secrets/kafka/password
Vault	Agent Unix socket	/vault/proxy/agent.sock

kubectl exec -n monadiam-apps <pod> -c service -- make migrate
kubectl exec -n monadiam-apps <pod> -c service -- make seed

---

Local Ports

Resource	Port
HTTP API	4003
PostgreSQL	6003 on host, 5432 inside Docker
Redis	7003 on host, 6379 inside Docker

---

Project Commands

Makefile	Description
Infrastructure
make env	Create .env from .env.local.example.
make build	Build the application image.
make up	Start service, Vault bootstrap, and Vault Agent.
make down	Stop and remove service containers.
make restart	Run make down and make up.
Development
make lint	Run ESLint code checks.
make lint-fix	Fix only Prettier violations and print changed file paths.
make tsc	Check TypeScript with tsc --noEmit.
make knip	Detect unused exports, files, and dependencies.
make secrets-check	Run the hook secret scan (staged changes).
make env-check	Validate environment DTO, templates and injected keys.
make intl-types	Generate TypeScript types from the translation dictionaries.
make intl-check	Run all six dictionary checks used by the Git hook.
make lsp	Start the local TypeScript MCP server over stdio.
make graphify	Create or update the local code graph and Markdown report.
make graphify-rebuild	Rescan all code files and regenerate the report.
make graphify-html	Update the graph and report, then export HTML visualization.
make swagger	Generate the OpenAPI Swagger JSON file.
make postman	Generate and patch the Postman collection JSON file.
make docs	Generate Swagger and Postman documentation artifacts.
Database
make migrate	Apply pending MikroORM migrations in the running service container.
make migration name="..."	Generate a MikroORM migration in the running service container.
make empty-migration name="..."	Generate a blank MikroORM migration.
make seed	Run the PostgreSQL seeder in the running service container.
Container / GHCR
make image	Build the production image; accepts IMAGE, BASE_IMAGE, VCS_REF.
make image-publish	Publish the commit SHA image to GHCR (CI).
make image-release	Tag the published SHA image with the package version (CI).
make image-cleanup	Retain 10 SHA-only image versions (CI).
Test
make test	Run unit and integration tests (Docker required).
make utest	Run the complete unit suite.
make itest	Run integration tests (Docker required).
make coverage-unit	Run unit tests with coverage in coverage/unit.
make coverage-integration	Run integration tests with coverage in coverage/integration.
make coverage	Run both suites with combined coverage in coverage/all.

---

Container package (GHCR)

ghcr.io/monadiam/notification-service

Event	Action
PR to dev	Existing checks and production image build; no publication
Push to dev	Build merged commit and publish sha-<commit>
Tag vX.Y.Z	Require matching package.json version and a commit in dev; tag its SHA image as X.Y.Z without rebuilding
Cleanup	Retain 10 SHA-only versions; preserve release tags
Stand	Pin the released image by digest

CI, publication, release, package operations.

Dockerfile targets: development for Compose and migration tooling; runner for GHCR, with production dependencies, compiled application and TypeScript sources for CLI commands. Both targets include make and cached pnpm; startup runs the service only.

---

Releasing a new version

1. Prepare a branch and set version in package.json (1.0.0 for the first release):

git switch dev
git pull --ff-only
git switch -c chore/release-v1.0.0
# Update package.json before committing.
git add package.json
git commit -m "chore: release v1.0.0"
git push -u origin chore/release-v1.0.0

2. Open a PR into dev, pass CI, merge and wait for Publish service image to succeed.
3. Tag the published commit; the tag must match package.json:

git switch dev
git pull --ff-only
git tag v1.0.0
git push origin v1.0.0

---