Event-Driven Notification Service

Project overview

Implement event-based email, SMS or in-app notification orchestration with retries, idempotency and delivery status. The project is intended as an industry-inspired engineering exercise: define a useful scope, implement an end-to-end workflow, validate it with tests and explain the trade-offs. The final scope should be agreed with the mentor or project owner based on the team's experience, available time and learning objectives.

Business problem and users

Applications often send notifications directly from business logic, creating tight coupling and inconsistent retry behaviour. A shared service should accept events, select eligible channels and track delivery outcomes without sending duplicate messages.

The primary users are application developer, support operator and service administrator. Start by writing two or three user journeys for these roles and identify where permissions, approvals or audit history are needed. Avoid building screens before the underlying workflow and its acceptance criteria are clear.

Proposed scope and core capabilities

The initial release should focus on a coherent, demonstrable vertical slice, then add the following capabilities in priority order:

• An: An event ingestion API with schema validation
• Templates: Templates with locale, channel and variable validation
• Recipient: Recipient preferences, consent and quiet-hour rules
• Queue-based: Queue-based asynchronous delivery using provider adapters or a mock provider
• Retry: Retry policy with backoff, dead-letter handling and idempotency keys
• Delivery: Delivery status, correlation IDs and operational metrics
• An: An operator view for failed messages and safe replay

Key workflow

A representative workflow should cover the complete journey rather than isolated CRUD screens: An event ingestion API with schema validation → Templates with locale → Recipient preferences → Queue-based asynchronous delivery using provider adapters or a mock provider → Retry policy with backoff. Define the allowed status transitions, validation rules, error states and the actions a user can take at each step. Where an external integration is not available, use a clearly labelled adapter or mock service and document its limitations.

Suggested data model

The main domain entities include: NotificationEvent, Template, RecipientPreference, DeliveryAttempt, Provider, IdempotencyKey and DeadLetterRecord. Define primary keys, relationships, required fields, uniqueness constraints and lifecycle timestamps. Document which data is authoritative and which values are derived. Use database migrations and seed data so another developer can reproduce the environment reliably.

Suggested architecture and technology

Use a modular architecture with a clear separation between the user interface, application/use-case logic, domain rules and persistence. A web UI backed by a REST API and relational database is a suitable default; adapt it when the requirements justify another approach.

• Frontend: React, Angular or Blade for a web interface; React Native/Expo only if a mobile experience adds clear value.
• Backend: Laravel, FastAPI, Spring Boot or ASP.NET Core, chosen to match the team's learning goals.
• Data: PostgreSQL or MySQL for transactional records; introduce Redis, a queue, search index or vector store only when a concrete requirement warrants it.
• Integration boundaries: isolate email, payment, OCR, maps, AI or other external providers behind adapters so they can be mocked in tests.
• Delivery: Git-based collaboration, issue tracking, automated checks, Docker where useful and a repeatable deployment procedure.

Before implementation, produce a context/component diagram, a simple data model and an API contract for the most important workflow. Record significant choices and alternatives in short Architecture Decision Records (ADRs).

Security, privacy and quality

Retries can cause duplicate or unwanted messages. Make delivery attempts observable, avoid storing unnecessary personal data and ensure replay actions are permission-protected.

At minimum, implement server-side validation, authentication where required, role-based authorization, safe error responses, appropriate logging and tests for important business rules. Do not commit credentials or production data. Use synthetic sample data for demonstrations and define a backup/recovery approach appropriate to the scope.

Testing and acceptance criteria

The project should be considered ready for demonstration when:

• A new developer can set up and run it using the README without undocumented manual steps.
• The main user journey works from start to finish, including at least one invalid-input or failure scenario.
• Business rules and state transitions are covered by automated tests.
• Unauthorized users cannot access restricted actions or records.
• Data integrity constraints and error messages are meaningful and consistent.
• The interface handles loading, empty, success and error states and remains usable on common screen sizes.
• Logs or audit history make important state changes explainable without exposing secrets.
• The team can demonstrate the system and explain architecture, trade-offs, known limitations and next steps.

Suggested milestones

1. Discovery and scope: confirm personas, problem statement, user journeys, exclusions and acceptance criteria.
2. Design: create the domain model, workflow/state diagram, API contract and initial architecture decisions.
3. Foundation: set up repository, coding conventions, environment configuration, migrations, seed data and CI checks.
4. Vertical slice: implement one complete user journey from UI to API and database, including validation and tests.
5. Feature expansion: add the remaining high-priority capabilities incrementally and review progress at each milestone.
6. Hardening: test permissions, edge cases, failure handling, accessibility, performance and data quality as appropriate.
7. Release and demonstration: deploy to a suitable test environment, complete the runbook and present the system.

Expected deliverables

• Problem statement, scope, personas and acceptance criteria.
• Architecture/context diagram, workflow diagram and data model.
• Source code, database migrations, seed data and sample configuration.
• API documentation or equivalent interface documentation.
• Automated tests and a summary of test results.
• README covering prerequisites, setup, environment variables, run commands and troubleshooting.
• Deployment notes, known limitations, security considerations and a demonstration plan.
• A short retrospective describing decisions made, challenges encountered and improvements proposed.

Advanced extensions

Introduce priority queues, per-tenant quotas, provider failover or event schema versioning. Treat extensions as optional; first complete and test the core workflow. Any AI or predictive component should have a baseline, an evaluation approach and a clear explanation of its limitations.

Assumptions and project boundaries

This is a proposed project brief, not a claim that the software is already implemented or ready for production. Exact scope, milestones, technology choices and mentoring arrangements should be agreed before work starts. Production use may require additional legal, regulatory, security, operational or domain-expert review beyond the learning prototype.