Docs/audit logging system spec

.kiro/specs/audit-logging-system/.config.kiro

@@ -0,0 +1 @@
+{"specId": "audit-logging-system", "workflowType": "requirements-first", "specType": "feature"}

.kiro/specs/audit-logging-system/design.md

@@ -0,0 +1,95 @@
+# Design Document
+
+## Overview
+
+This design implements a comprehensive audit logging system for recording notification lifecycle events with immutability and queryability guarantees.
+
+## Architecture
+
+### Data Model
+
+```typescript
+interface AuditLogEntry {
+  entryId: string;              // Unique identifier
+  notificationId: string;       // Reference to notification
+  timestamp: number;            // Unix timestamp
+  eventType: EventType;         // CREATION, DELIVERY_ATTEMPT, etc.
+  actor: string;                // Address or identifier
+  status: 'success' | 'failure'; // Operation status
+  metadata: {
+    recipient?: string;
+    channel?: string;
+    errorReason?: string;
+    retryCount?: number;
+    [key: string]: any;          // Flexible for event-specific data
+  };
+  createdAt: number;            // When log was created
+  immutable: true;              // Flag indicating immutability
+}
+
+enum EventType {
+  CREATION = 'CREATION',
+  DELIVERY_ATTEMPT = 'DELIVERY_ATTEMPT',
+  DELIVERY_SUCCESS = 'DELIVERY_SUCCESS',
+  DELIVERY_FAILURE = 'DELIVERY_FAILURE',
+  ACKNOWLEDGMENT = 'ACKNOWLEDGMENT'
+}
+```
+
+### Storage Strategy
+
+1. **Primary Storage**: Database/persistent store for all audit logs
+2. **Indexing**: Create indexes on notificationId, recipient, eventType, timestamp
+3. **Archival**: Move logs older than retention period to archive
+4. **Performance**: Use read-optimized queries for audit log retrieval
+
+### Query Interface
+
+```typescript
+interface AuditLogQuery {
+  notificationId?: string;
+  recipient?: string;
+  eventType?: EventType | EventType[];
+  dateRange?: {
+    startTime: number;
+    endTime: number;
+  };
+  actor?: string;
+  limit?: number;     // Default 100, max 1000
+  offset?: number;    // For pagination
+}
+
+interface QueryResult {
+  entries: AuditLogEntry[];
+  total: number;
+  hasMore: boolean;
+}
+```
+
+### Integration Points
+
+1. **Event Subscriber**: Log CREATION events
+2. **Discord Service**: Log DELIVERY_ATTEMPT, DELIVERY_SUCCESS, DELIVERY_FAILURE
+3. **Notification Expiration**: Log EXPIRATION events
+4. **API Endpoints**: Provide query interface for clients
+
+### Immutability Enforcement
+
+- No UPDATE operations on audit logs
+- DELETE only through archive/purge administrative functions
+- Logs stored in append-only structure
+- Database constraints to prevent modification
+
+## Performance Considerations
+
+- Indexes on query fields (notificationId, recipient, eventType, timestamp)
+- Pagination for large queries
+- Cache frequently accessed audit logs
+- Archive old logs to separate storage
+
+## Compliance and Retention
+
+- Default retention: 365 days
+- Configurable retention policy
+- Audit trails for who accessed what logs
+- Compliance reporting endpoints

.kiro/specs/audit-logging-system/requirements.md

@@ -0,0 +1,97 @@
+# Requirements Document
+
+## Introduction
+
+This feature creates an audit logging system that records notification lifecycle events for compliance and operational monitoring, enabling complete visibility into delivery attempts and outcomes.
+
+## Glossary
+
+- **Audit Log**: Immutable record of notification lifecycle events
+- **Lifecycle Event**: Creation, delivery attempt, delivery failure, acknowledgment
+- **Audit Record**: Single entry in the audit log with timestamp and event details
+- **Query Endpoint**: API or function to retrieve and filter audit logs
+- **Immutable**: Cannot be modified or deleted after creation
+- **Compliance**: Meeting regulatory and operational requirements
+
+## Requirements
+
+### Requirement 1: Audit Event Schema
+
+**User Story:** As a compliance officer, I want a well-defined audit event schema, so that all events are recorded consistently.
+
+#### Acceptance Criteria
+
+1. THE audit event schema SHALL include: eventId, notificationId, timestamp, eventType, actor, status, metadata
+2. THE eventType SHALL be one of: CREATION, DELIVERY_ATTEMPT, DELIVERY_SUCCESS, DELIVERY_FAILURE, ACKNOWLEDGMENT
+3. THE actor field SHALL identify who/what triggered the event
+4. THE metadata field SHALL be flexible JSON object for event-specific data
+5. ALL fields SHALL be optional except eventId, timestamp, and eventType
+
+### Requirement 2: Creation Event Logging
+
+**User Story:** As an auditor, I want to see when notifications are created, so that I can track notification lifecycle start.
+
+#### Acceptance Criteria
+
+1. WHEN a notification is created, THE system SHALL log a CREATION event
+2. THE CREATION event SHALL include: notificationId, creator address, recipient, title, content
+3. THE CREATION event SHALL be logged before notification is marked active
+4. THE event SHALL not be lost even if creation partially fails
+
+### Requirement 3: Delivery Attempt Logging
+
+**User Story:** As an operations manager, I want to see all delivery attempts, so that I can troubleshoot delivery issues.
+
+#### Acceptance Criteria
+
+1. WHEN delivery is attempted, THE system SHALL log a DELIVERY_ATTEMPT event
+2. THE DELIVERY_ATTEMPT event SHALL include: notificationId, recipient, channel (Discord, etc.), timestamp
+3. IF delivery succeeds, THE system SHALL log DELIVERY_SUCCESS event
+4. IF delivery fails, THE system SHALL log DELIVERY_FAILURE event with error reason
+5. EACH delivery attempt SHALL be logged independently
+
+### Requirement 4: Failure Logging
+
+**User Story:** As a support engineer, I want detailed failure logs, so that I can diagnose delivery problems.
+
+#### Acceptance Criteria
+
+1. WHEN delivery fails, THE system SHALL log failure reason/error message
+2. THE failure log SHALL include: error type, error message, retry count, next retry time (if applicable)
+3. RETRIES SHALL be logged as separate events
+4. FAILURE logs SHALL be retained for troubleshooting
+
+### Requirement 5: Acknowledgment Logging
+
+**User Story:** As a product manager, I want to see when notifications are acknowledged, so that I can track user engagement.
+
+#### Acceptance Criteria
+
+1. WHEN a notification is acknowledged, THE system SHALL log an ACKNOWLEDGMENT event
+2. THE ACKNOWLEDGMENT event SHALL include: notificationId, recipient, timestamp
+3. MULTIPLE acknowledgments for same notification SHALL be supported
+4. ACKNOWLEDGMENT timing relative to delivery SHALL be trackable
+
+### Requirement 6: Query Endpoints
+
+**User Story:** As a system user, I want to query audit logs, so that I can analyze notification history.
+
+#### Acceptance Criteria
+
+1. THE system SHALL provide query endpoint for retrieving audit logs
+2. QUERIES SHALL support filtering by: notificationId, recipient, eventType, dateRange, actor
+3. QUERIES SHALL return results in chronological order
+4. QUERIES SHALL support pagination for large result sets
+5. QUERIES SHALL be fast (sub-second response times)
+
+### Requirement 7: Immutability and Retention
+
+**User Story:** As a compliance manager, I want audit logs to be immutable, so that historical records cannot be tampered with.
+
+#### Acceptance Criteria
+
+1. AUDIT logs SHALL NOT be modifiable or deletable after creation
+2. AUDIT logs SHALL be retained for minimum 365 days
+3. ARCHIVED logs older than retention period MAY be removed
+4. RETENTION policy SHALL be configurable
+5. DELETION of logs SHALL only be allowed through privileged administrative function