hrynco-notification-service/README.md

# hrynco-notification-service

Production image references now use `registry.hrynco.com`, preserving the existing image-tag variables. Contracts package repository metadata uses `gitea.hrynco.com`. These are source configuration changes; production containers and live CI configuration were not restarted or updated by this migration.

## Documentation

- [Email template definitions and service languages](docs/email-template-localizations.md)
- [Service and whole-template API for AI clients](docs/email-template-definition-api.md)
- [ItemTracker outbox email consumer](docs/itemtracker-outbox-email-consumer.md)
- [Shared Notification Service Kubernetes package](docker/kubernetes/shared-notification/README.md)

## Windows host development

For the owner's host development workflow, run Web in Rider with the Development
profile (`localhost:5433` PostgreSQL, HTTP `localhost:5188`) and keep Docker Web
stopped. Infrastructure can remain in the existing Docker stack. Web does not apply
schema migrations automatically. The owner's local database is prepared only when
they choose to run the current Migrator with an explicit connection setting.
See [template migration and local setup](docs/email-template-localizations.md) for
backup, conflict, compatibility and validation details. The full Docker installation
below is a separate complete-stack workflow.

## Development environment

The development Docker Compose stack runs PostgreSQL, RabbitMQ, database migrations,
the Notification Service Web and Worker applications, Seq, and Mailpit.

Prerequisite: install and start Docker Desktop. Then run the installation script from
the repository root:

```powershell
.\docker\environments\install-development.cmd
```

The script validates Docker and the Compose configuration, builds the application
images, starts the complete stack in the background, and prints container status and
the main development URLs. It can also be launched directly from File Explorer or
from another working directory.

To validate the setup without building images or creating containers, run:

```powershell
.\docker\environments\install-development.cmd --validate-only
```

By default, the script uses the tracked `docker/environments/.env.Development` file:

```dotenv
DB_NAME=notification_service
DB_USER=postgres
DB_PASS=postgres
VOLUME_PREFIX=ns-dev
RABBITMQ_USER=guest
RABBITMQ_PASSWORD=guest
RABBITMQ_AMQP_PORT=5672
RABBITMQ_MANAGEMENT_PORT=15672
WEB_PORT=5200
DEVELOPMENT_EMAIL_SERVICE_NAME=TestService
```

To use personal values, copy it to the Git-ignored
`docker/environments/.env.local`, adjust the values, and run Docker Compose manually:

```powershell
docker compose --env-file docker/environments/.env.local `
  -f docker/environments/docker-compose.yml `
  -f docker/environments/docker-compose.Development.yml `
  up --build -d
```

After startup, the main development endpoints are:

- Notification Service admin: `http://localhost:5200/admin/channels`
- Services and their notification templates: `http://localhost:5200/admin/services`
- RabbitMQ management: `http://localhost:15672` (`guest` / `guest`)
- Mailpit inbox: `http://localhost:8025`
- Seq logs: `http://localhost:5342`
- PostgreSQL: `localhost:5433`

During development migrations, the stack idempotently creates an active Mailpit SMTP
channel and a neutral English `TestEmail` template for
`DEVELOPMENT_EMAIL_SERVICE_NAME`. Existing channels and templates are never
overwritten. Change that environment value when the publisher uses another service
name.

Check container status and follow Worker logs:

```powershell
docker compose --env-file docker/environments/.env.local `
  -f docker/environments/docker-compose.yml `
  -f docker/environments/docker-compose.Development.yml `
  ps

docker compose --env-file docker/environments/.env.local `
  -f docker/environments/docker-compose.yml `
  -f docker/environments/docker-compose.Development.yml `
  logs -f worker
```

Stop the environment without deleting its database and RabbitMQ volumes:

```powershell
docker compose --env-file docker/environments/.env.local `
  -f docker/environments/docker-compose.yml `
  -f docker/environments/docker-compose.Development.yml `
  down
```

See the [ItemTracker consumer guide](docs/itemtracker-outbox-email-consumer.md#local-end-to-end-setup)
for the complete end-to-end setup.

## Notification worker flow

```mermaid
flowchart TD
    A[Worker host starts] --> B[Load config and register services]
    B --> C[Start SendEmailConsumer]
    C --> D[Receive message from notification.send-email]
    D --> E[Validate Notification.SendEmail.v1 metadata and payload]
    E --> F[Resolve SendEmailService]
    F --> G[Pick channel and exact-language template]
    G --> H[Validate variables and render email content]
    H --> I[Send via SMTP]
    I --> J[Update usage counters]
    J --> K[Optionally publish result to reply queue]
    K --> L[Acknowledge RabbitMQ delivery]
    I -. failure .-> M[Log and retry]
    M -->|retries exhausted| N[Publish terminal failure result]
    N --> O[Nack original delivery without requeue]
```

Template variables are treated as plain text. The worker HTML-encodes every variable while
rendering `HtmlBody`; subject and plain-text body interpolation preserve the original value.
Templates must express markup in `body.html` instead of supplying HTML through variables.