ApexCart Technical Design Doc: Unified Notification Engine

### Grammar Focus: Nominalisation in Technical Writing

In formal software architecture documents, we often convert verbs and adjectives into nouns (a process known as nominalisation). This shifting of grammatical categories moves the focus from the active agents performing the actions to the actions, states, and objects themselves, creating a much more objective, professional, and authoritative tone. It is a highly effective way to make your technical writing sound polished.

| Verb / Adjective | Nominalised Noun | Example |
| :--- | :--- | :--- |
| decide | decision | The decision to migrate was approved. |
| available | availability | We must guarantee high availability. |
| implement | implementation | The implementation of this cache is critical. |
| reduce | reduction | A reduction in latency was observed. |

Instead of writing 'We decided to prioritize speed because we want to make sure the system is highly available,' we write: 'The decision to prioritize speed was driven by the requirement for high availability.'

*

Document ID: DD-2024-892
Project: ApexCart Unified Notification Engine (UNE)
Authors: Michelle, Sam, Samantha
Status: Draft / Request for Comments

1. Background & Problem Statement
The current architecture of ApexCart relies heavily on tightly coupled notification services, where individual microservices independently manage their connection to SMTP and SMS gateways. This tight coupling has led to a complete lack of a clear service boundary, resulting in duplicated code and highly inconsistent delivery configurations. Consequently, any modification of retry policies requires the deployment of multiple downstream services. Our primary objective is the creation of a centralized notification hub that provides a loosely coupled, highly available interface for all ApexCart services.

2. Rationale
The decision to introduce a unified engine is driven entirely by the necessity for improved reliability, structural simplification, and centralized rate-limiting. A high-level overview of our current system metrics shows a significant reduction in delivery success during peak traffic hours due to rate limits imposed by external APIs. The introduction of a persistent queue will allow the mediation of traffic spikes, ensuring that external provider limits are not exceeded. Furthermore, this migration will enable better stakeholder alignment regarding our communication policies.

3. Goals
- Centralization: The consolidation of all outbound communication templates into a single secure repository.
- Resilience: The implementation of automatic retry mechanisms with exponential backoff configurations.
- Observability: The provision of real-time delivery metrics to map out latency bottlenecks across different providers.
- Ownership: Cultivating an ownership mentality among distinct product teams by allowing them self-service template management.

4. Non-Goals
The identification of non-goals is crucial to prevent scope creep. This document does not address the migration of historical notification logs, which will remain in the legacy cold storage database indefinitely. The real-time translation of notification templates is completely out of scope; localization will be handled upstream. We will not attempt to rewrite the user profile service, as we expect teams to prioritize ruthlessly. Finally, this design doc will not resolve the CEO’s urgent request to send system outage alerts to enterprise clients via physical paper fax.

5. Open Questions
The resolution of the following questions is required before final sign-off. First, we must determine the availability of secondary SMS gateways in the UK region to prevent single points of failure. Second, the potential performance degradation during high-throughput stress testing needs careful evaluation by the performance engineering team.

Read again and choose the right answer

What is the main problem with the current ApexCart notification architecture?

• It relies on a physical paper fax gateway.
• It has tightly coupled services with no clear service boundary.
• It lacks a persistent queue for SMS delivery.

Why is the introduction of a persistent queue proposed in the rationale section?

• To allow the mediation of traffic spikes and avoid exceeding external API limits.
• To handle real-time translation of templates.
• To migrate historical notification logs to cold storage.

Which of the following is explicitly listed as a non-goal in the document?

• Implementing automatic retry mechanisms.
• Consolidating outbound templates.
• Rewriting the user profile service.

What is the dry joke at the end of the non-goals section?

• The system will not support sending outage alerts via physical fax.
• The CEO will personally sign off on every notification.
• The team refuses to localize any templates for the UK region.

Sources: photo by Pavel Danilyuk on Pexels