alla-allaos-fullstack/docs/implementation/task-p.7.1-implementation.md

Task P.7.1 Implementation Report

Scope

This round starts Task P.7.1 by extending the existing notification foundation into a reusable delivery layer for channel-based notifications, with email as the first implemented provider.

Review Summary

Reviewed before implementation:

• AGENTS.md
• docs/standards/project-foundations.md
• docs/standards/architecture-rules.md
• docs/standards/ui-ux-rules.md
• docs/standards/task-review-checklist.md
• docs/adr/0008-attachment-storage-strategy.md
• docs/adr/0009-approved-document-storage-lifecycle.md
• docs/implementation/task-f4-notification-framework-foundation.md
• docs/implementation/task-f5-approval-automation-foundation.md
• docs/implementation/task-i-storage-artifact-lifecycle.md
• docs/implementation/task-p.7-implementation.md

Discovery Findings

• The repo already had an in-app notification foundation from Task F4 using app_notification_events, app_notifications, app_notification_templates, and app_notification_deliveries.
• Approval automation from Task F5 already publishes reminder/escalation events and proves scheduler-oriented notification orchestration exists, but only for in-app delivery.
• Storage and immutable document delivery foundations already exist and are reusable through:
  • src/features/foundation/document-artifact/server/service.ts
  • src/features/foundation/document-library/server/service.ts
  • src/features/foundation/storage/service.ts
• There was no usable SMTP provider implementation in the workspace yet; nodemailer had to be added.
• There was no generic external-delivery history/queue log yet; the old app_notification_deliveries rows were still shaped around inbox notifications.

Delivered In This Round

• Expanded notification contracts in src/features/foundation/notifications/types.ts to cover channels, dispatch status, external recipients, template metadata, attachments, and provider interfaces.
• Extended notification template schema and added a new dispatch/history table in:
  • src/db/schema.ts
  • drizzle/0009_notification_delivery_foundation.sql
• Added reusable rendering, queue execution, attachment resolution, and provider plumbing:
  • src/features/foundation/notifications/server/template-renderer.ts
  • src/features/foundation/notifications/server/delivery-engine.ts
  • src/features/foundation/notifications/server/attachment-service.ts
  • src/features/foundation/notifications/server/email-provider.ts
  • src/features/foundation/notifications/server/provider-factory.ts
  • src/features/foundation/notifications/server/service.ts
• Added API entry points for the first reusable send/preview/history/detail/resend flow:
  • src/app/api/notifications/preview/route.ts
  • src/app/api/notifications/send/route.ts
  • src/app/api/notifications/history/route.ts
  • src/app/api/notifications/history/[id]/route.ts
  • src/app/api/notifications/history/[id]/resend/route.ts
• Added new permissions in src/lib/auth/rbac.ts:
  • notification.send
  • notification.resend
  • notification.manage_template
  • notification.view_history
• Kept the original approval bell/inbox flow intact by updating src/features/foundation/notifications/server/event-service.ts only where the richer template contract needed compatibility.

Design Notes

• The old in-app notification foundation remains the source of truth for header bell / inbox UX.
• The new delivery foundation uses a separate app_notification_dispatches log so external-channel delivery history does not depend on internal inbox rows.
• Attachment resolution is storage-backed only. It reads existing artifact/document-library files and does not regenerate PDFs during send.
• If a channel-specific template is missing, the new service falls back to the event's active in-app template so the API remains usable during migration.

Known Gaps After This Round

• No template management UI yet.
• No automated CRM event publication into email dispatch yet; CRM modules still need to call the new service/API explicitly.
• No seed update was added yet for dedicated email templates, so best experience currently comes from template override or the in-app fallback path.
• No Teams / LINE / Slack / SMS / web push provider implementations yet.
• No background worker process yet; queue behavior is modeled in persisted dispatch status plus retry semantics, but still executed synchronously in this round.