|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Notifier is Devtron's multi-channel notification service. It receives CI/CD pipeline events (via NATS JetStream or HTTP) and dispatches notifications to Slack, email (SES/SMTP), and webhooks. Built with TypeScript, Express, TypeORM (PostgreSQL), and NATS. |
| 8 | + |
| 9 | +## Build & Development Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +npm install # Install dependencies |
| 13 | +npm run dev # Dev server with nodemon (auto-reload) |
| 14 | +npm run dev:debug # Dev server with --inspect debugger |
| 15 | +npm run build-ts # Compile TypeScript to dist/ |
| 16 | +npm run serve # Run compiled JS from dist/ |
| 17 | +npm test <file> # Run a single test file, e.g.: npm test src/tests/notificationService.test.ts |
| 18 | +``` |
| 19 | + |
| 20 | +Requires Node.js >= 20. TypeScript strict mode is enabled but `noImplicitAny` and `strictNullChecks` are off. |
| 21 | + |
| 22 | +## Environment Variables |
| 23 | + |
| 24 | +| Variable | Default | Description | |
| 25 | +|----------|---------|-------------| |
| 26 | +| DB_HOST | localhost | PostgreSQL host | |
| 27 | +| DB_PORT | 5432 | PostgreSQL port | |
| 28 | +| DB_USER | user | PostgreSQL username | |
| 29 | +| DB_PWD | password | PostgreSQL password | |
| 30 | +| DB | orchestrator | Database name | |
| 31 | +| PORT | 3000 | HTTP server port | |
| 32 | +| NATS_URL | (none) | NATS server URL; NATS disabled if unset | |
| 33 | +| BASE_URL | (none) | Base URL for links embedded in notifications | |
| 34 | + |
| 35 | +## Architecture |
| 36 | + |
| 37 | +### Entry Point & Startup |
| 38 | + |
| 39 | +`src/server.ts` → connects to PostgreSQL (TypeORM), initializes all services via `src/services/serviceInitializer.ts` (manual DI), connects to NATS, starts Express on PORT. |
| 40 | + |
| 41 | +### Notification Flow |
| 42 | + |
| 43 | +``` |
| 44 | +Event Source (NATS JetStream or POST /notify/v2) |
| 45 | + → NotificationService.sendNotificationV2() |
| 46 | + → Loads notification_settings + templates from DB |
| 47 | + → json-rules-engine evaluates filter conditions |
| 48 | + → Dispatches to matching Handler implementations: |
| 49 | + SlackService → Slack webhook API (via notifme-sdk) |
| 50 | + SESService → AWS SES (via notifme-sdk) |
| 51 | + SMTPService → SMTP server (via notifme-sdk) |
| 52 | + WebhookService → HTTP POST to user-configured URLs (via axios) |
| 53 | + → Logs results to notifier_event_logs table |
| 54 | +``` |
| 55 | + |
| 56 | +### Handler Interface |
| 57 | + |
| 58 | +All destination handlers implement `Handler` (defined in `src/notification/service/notificationService.ts`) with: |
| 59 | +- `handle(event, templates, setting, configsMap, destinationMap)` — orchestrates a single notification send |
| 60 | +- `sendNotification(event, sdk, template)` — performs the actual send |
| 61 | + |
| 62 | +### Template System |
| 63 | + |
| 64 | +Mustache templates live in `src/templates/{slack,ses,smtp}/{CI,CD,BASE}/`. Files are named by `EVENT_TYPE` enum value (e.g., `1.mustache` for Trigger). `TemplateLoader` reads them at startup. `MustacheHelper` parses raw events into typed objects with boolean flags for conditional template rendering. |
| 65 | + |
| 66 | +### Event Types (`src/common/types.ts`) |
| 67 | + |
| 68 | +1=Trigger, 2=Success, 3=Fail, 4=Approval, 5=ConfigApproval, 6=Blocked, 7=ImagePromotion, 8=ImageScan, 9=ScoopNotification, 10=DeploymentApproved, 11=ConfigApproved, 12=PromotionApproved, 13=DeploymentCancelled, 14=ConfigCancelled, 15=PromotionCancelled |
| 69 | + |
| 70 | +### Key Directories |
| 71 | + |
| 72 | +- `src/notification/service/` — core NotificationService orchestration |
| 73 | +- `src/destination/destinationHandlers/` — channel-specific handlers (Slack, SES, SMTP, Webhook) |
| 74 | +- `src/entities/` — TypeORM entity models (notification_settings, slack_config, smtp_config, ses_config, webhook_config, events, users, notifier_event_logs) |
| 75 | +- `src/repository/` — data access layer wrapping TypeORM |
| 76 | +- `src/common/` — shared types, MustacheHelper (event parsing), EventLogBuilder, Prometheus metrics |
| 77 | +- `src/templates/` — Mustache templates organized by channel and pipeline type |
| 78 | +- `src/config/` — database, NATS, and logger configuration |
| 79 | +- `src/pubSub/` — NATS JetStream client |
| 80 | + |
| 81 | +### Dependency Injection |
| 82 | + |
| 83 | +Manual constructor injection in `src/services/serviceInitializer.ts`. No DI framework — all repositories, helpers, and handlers are instantiated explicitly and wired together. |
| 84 | + |
| 85 | +## Testing |
| 86 | + |
| 87 | +Tests use Mocha + Chai (BDD style) in `src/tests/`. The custom test runner (`test.ts`) accepts a single file path: |
| 88 | + |
| 89 | +```bash |
| 90 | +npm test src/tests/notificationService.test.ts |
| 91 | +npm test src/tests/approvalTemplateTest.ts |
| 92 | +``` |
| 93 | + |
| 94 | +Tests are standalone files — no shared setup/teardown infrastructure. |
0 commit comments