domain.events.data_events

src.domain.events.data_events

Data synchronization domain events (F7.7 Phase 2).

Pattern: 3 events per workflow (ATTEMPTED → SUCCEEDED/FAILED) - *Attempted: User initiated sync (before business logic) - *Succeeded: Operation completed successfully (after business commit) - *Failed: Operation failed (after business rollback)

Handlers: - LoggingEventHandler: ALL 3 events - AuditEventHandler: ALL 3 events

Workflows: 1. Account Sync: Sync account data from provider 2. Transaction Sync: Sync transaction data from provider 3. Holdings Sync: Sync holdings (positions) from provider 4. File Import: Import data from uploaded file

Classes

AccountSyncAttempted dataclass

Bases: DomainEvent

Account sync attempt initiated.

Triggers: - LoggingEventHandler: Log attempt - AuditEventHandler: Record ACCOUNT_SYNC_ATTEMPTED

Attributes:

Name	Type	Description
connection_id	UUID	Provider connection being synced.
user_id	UUID	User initiating sync.

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class AccountSyncAttempted(DomainEvent):
    """Account sync attempt initiated.

    Triggers:
    - LoggingEventHandler: Log attempt
    - AuditEventHandler: Record ACCOUNT_SYNC_ATTEMPTED

    Attributes:
        connection_id: Provider connection being synced.
        user_id: User initiating sync.
    """

    connection_id: UUID
    user_id: UUID

AccountSyncSucceeded dataclass

Bases: DomainEvent

Account sync completed successfully.

Triggers: - LoggingEventHandler: Log success - AuditEventHandler: Record ACCOUNT_SYNC_SUCCEEDED

Attributes:

Name	Type	Description
connection_id	UUID	Provider connection synced.
user_id	UUID	User who initiated sync.
account_count	int	Number of accounts synced.

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class AccountSyncSucceeded(DomainEvent):
    """Account sync completed successfully.

    Triggers:
    - LoggingEventHandler: Log success
    - AuditEventHandler: Record ACCOUNT_SYNC_SUCCEEDED

    Attributes:
        connection_id: Provider connection synced.
        user_id: User who initiated sync.
        account_count: Number of accounts synced.
    """

    connection_id: UUID
    user_id: UUID
    account_count: int

AccountSyncFailed dataclass

Bases: DomainEvent

Account sync failed.

Triggers: - LoggingEventHandler: Log failure - AuditEventHandler: Record ACCOUNT_SYNC_FAILED

Attributes:

Name	Type	Description
connection_id	UUID	Provider connection attempted.
user_id	UUID	User who initiated sync.
reason	str	Failure reason (e.g., "connection_not_found", "provider_error", "authentication_failed").

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class AccountSyncFailed(DomainEvent):
    """Account sync failed.

    Triggers:
    - LoggingEventHandler: Log failure
    - AuditEventHandler: Record ACCOUNT_SYNC_FAILED

    Attributes:
        connection_id: Provider connection attempted.
        user_id: User who initiated sync.
        reason: Failure reason (e.g., "connection_not_found", "provider_error",
            "authentication_failed").
    """

    connection_id: UUID
    user_id: UUID
    reason: str

TransactionSyncAttempted dataclass

Bases: DomainEvent

Transaction sync attempt initiated.

Triggers: - LoggingEventHandler: Log attempt - AuditEventHandler: Record TRANSACTION_SYNC_ATTEMPTED

Attributes:

Name	Type	Description
connection_id	UUID	Provider connection being synced.
user_id	UUID	User initiating sync.
account_id	UUID | None	Specific account if targeted sync (optional).

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class TransactionSyncAttempted(DomainEvent):
    """Transaction sync attempt initiated.

    Triggers:
    - LoggingEventHandler: Log attempt
    - AuditEventHandler: Record TRANSACTION_SYNC_ATTEMPTED

    Attributes:
        connection_id: Provider connection being synced.
        user_id: User initiating sync.
        account_id: Specific account if targeted sync (optional).
    """

    connection_id: UUID
    user_id: UUID
    account_id: UUID | None = None

TransactionSyncSucceeded dataclass

Bases: DomainEvent

Transaction sync completed successfully.

Triggers: - LoggingEventHandler: Log success - AuditEventHandler: Record TRANSACTION_SYNC_SUCCEEDED

Attributes:

Name	Type	Description
connection_id	UUID	Provider connection synced.
user_id	UUID	User who initiated sync.
account_id	UUID | None	Specific account if targeted sync (optional).
transaction_count	int	Number of transactions synced.

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class TransactionSyncSucceeded(DomainEvent):
    """Transaction sync completed successfully.

    Triggers:
    - LoggingEventHandler: Log success
    - AuditEventHandler: Record TRANSACTION_SYNC_SUCCEEDED

    Attributes:
        connection_id: Provider connection synced.
        user_id: User who initiated sync.
        account_id: Specific account if targeted sync (optional).
        transaction_count: Number of transactions synced.
    """

    connection_id: UUID
    user_id: UUID
    account_id: UUID | None
    transaction_count: int

TransactionSyncFailed dataclass

Bases: DomainEvent

Transaction sync failed.

Triggers: - LoggingEventHandler: Log failure - AuditEventHandler: Record TRANSACTION_SYNC_FAILED

Attributes:

Name	Type	Description
connection_id	UUID	Provider connection attempted.
user_id	UUID	User who initiated sync.
account_id	UUID | None	Specific account if targeted sync (optional).
reason	str	Failure reason (e.g., "connection_not_found", "provider_error", "date_range_invalid").

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class TransactionSyncFailed(DomainEvent):
    """Transaction sync failed.

    Triggers:
    - LoggingEventHandler: Log failure
    - AuditEventHandler: Record TRANSACTION_SYNC_FAILED

    Attributes:
        connection_id: Provider connection attempted.
        user_id: User who initiated sync.
        account_id: Specific account if targeted sync (optional).
        reason: Failure reason (e.g., "connection_not_found", "provider_error",
            "date_range_invalid").
    """

    connection_id: UUID
    user_id: UUID
    account_id: UUID | None
    reason: str

HoldingsSyncAttempted dataclass

Bases: DomainEvent

Holdings sync attempt initiated.

Triggers: - LoggingEventHandler: Log attempt - AuditEventHandler: Record HOLDINGS_SYNC_ATTEMPTED

Attributes:

Name	Type	Description
account_id	UUID	Account being synced.
user_id	UUID	User initiating sync.

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class HoldingsSyncAttempted(DomainEvent):
    """Holdings sync attempt initiated.

    Triggers:
    - LoggingEventHandler: Log attempt
    - AuditEventHandler: Record HOLDINGS_SYNC_ATTEMPTED

    Attributes:
        account_id: Account being synced.
        user_id: User initiating sync.
    """

    account_id: UUID
    user_id: UUID

HoldingsSyncSucceeded dataclass

Bases: DomainEvent

Holdings sync completed successfully.

Triggers: - LoggingEventHandler: Log success - AuditEventHandler: Record HOLDINGS_SYNC_SUCCEEDED

Attributes:

Name	Type	Description
account_id	UUID	Account synced.
user_id	UUID	User who initiated sync.
holding_count	int	Number of holdings synced.

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class HoldingsSyncSucceeded(DomainEvent):
    """Holdings sync completed successfully.

    Triggers:
    - LoggingEventHandler: Log success
    - AuditEventHandler: Record HOLDINGS_SYNC_SUCCEEDED

    Attributes:
        account_id: Account synced.
        user_id: User who initiated sync.
        holding_count: Number of holdings synced.
    """

    account_id: UUID
    user_id: UUID
    holding_count: int

HoldingsSyncFailed dataclass

Bases: DomainEvent

Holdings sync failed.

Triggers: - LoggingEventHandler: Log failure - AuditEventHandler: Record HOLDINGS_SYNC_FAILED

Attributes:

Name	Type	Description
account_id	UUID	Account attempted.
user_id	UUID	User who initiated sync.
reason	str	Failure reason (e.g., "account_not_found", "provider_error", "holdings_not_supported").

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class HoldingsSyncFailed(DomainEvent):
    """Holdings sync failed.

    Triggers:
    - LoggingEventHandler: Log failure
    - AuditEventHandler: Record HOLDINGS_SYNC_FAILED

    Attributes:
        account_id: Account attempted.
        user_id: User who initiated sync.
        reason: Failure reason (e.g., "account_not_found", "provider_error",
            "holdings_not_supported").
    """

    account_id: UUID
    user_id: UUID
    reason: str

FileImportAttempted dataclass

Bases: DomainEvent

File import attempt initiated.

Triggers: - LoggingEventHandler: Log attempt - AuditEventHandler: Record FILE_IMPORT_ATTEMPTED

Attributes:

Name	Type	Description
user_id	UUID	User importing file.
provider_slug	str	Provider identifier (e.g., "chase_file").
file_name	str	Original filename.
file_format	str	File format (e.g., "qfx", "ofx", "csv").

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class FileImportAttempted(DomainEvent):
    """File import attempt initiated.

    Triggers:
    - LoggingEventHandler: Log attempt
    - AuditEventHandler: Record FILE_IMPORT_ATTEMPTED

    Attributes:
        user_id: User importing file.
        provider_slug: Provider identifier (e.g., "chase_file").
        file_name: Original filename.
        file_format: File format (e.g., "qfx", "ofx", "csv").
    """

    user_id: UUID
    provider_slug: str
    file_name: str
    file_format: str

FileImportSucceeded dataclass

Bases: DomainEvent

File import completed successfully.

Triggers: - LoggingEventHandler: Log success - AuditEventHandler: Record FILE_IMPORT_SUCCEEDED

Attributes:

Name	Type	Description
user_id	UUID	User who imported file.
provider_slug	str	Provider identifier.
file_name	str	Original filename.
file_format	str	File format.
account_count	int	Number of accounts created/updated.
transaction_count	int	Number of transactions imported.

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class FileImportSucceeded(DomainEvent):
    """File import completed successfully.

    Triggers:
    - LoggingEventHandler: Log success
    - AuditEventHandler: Record FILE_IMPORT_SUCCEEDED

    Attributes:
        user_id: User who imported file.
        provider_slug: Provider identifier.
        file_name: Original filename.
        file_format: File format.
        account_count: Number of accounts created/updated.
        transaction_count: Number of transactions imported.
    """

    user_id: UUID
    provider_slug: str
    file_name: str
    file_format: str
    account_count: int
    transaction_count: int

FileImportFailed dataclass

Bases: DomainEvent

File import failed.

Triggers: - LoggingEventHandler: Log failure - AuditEventHandler: Record FILE_IMPORT_FAILED

Attributes:

Name	Type	Description
user_id	UUID	User who attempted import.
provider_slug	str	Provider identifier.
file_name	str	Original filename.
file_format	str	File format.
reason	str	Failure reason (e.g., "parse_error", "unsupported_format", "invalid_file_structure").

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class FileImportFailed(DomainEvent):
    """File import failed.

    Triggers:
    - LoggingEventHandler: Log failure
    - AuditEventHandler: Record FILE_IMPORT_FAILED

    Attributes:
        user_id: User who attempted import.
        provider_slug: Provider identifier.
        file_name: Original filename.
        file_format: File format.
        reason: Failure reason (e.g., "parse_error", "unsupported_format",
            "invalid_file_structure").
    """

    user_id: UUID
    provider_slug: str
    file_name: str
    file_format: str
    reason: str

FileImportProgress dataclass

Bases: DomainEvent

File import progress update (emitted periodically during import).

This is an OPERATIONAL event, not part of the 3-state workflow. Used for real-time progress updates via SSE.

Triggers: - LoggingEventHandler: Log progress (DEBUG level) - SSEEventHandler: Broadcast via SSE

Attributes:

Name	Type	Description
user_id	UUID	User importing file.
provider_slug	str	Provider identifier.
file_name	str	Original filename.
file_format	str	File format.
progress_percent	int	Progress percentage (0-100).
records_processed	int	Number of records processed so far.
total_records	int	Total records to process (may be estimate).

Source code in src/domain/events/data_events.py

@dataclass(frozen=True, kw_only=True)
class FileImportProgress(DomainEvent):
    """File import progress update (emitted periodically during import).

    This is an OPERATIONAL event, not part of the 3-state workflow.
    Used for real-time progress updates via SSE.

    Triggers:
    - LoggingEventHandler: Log progress (DEBUG level)
    - SSEEventHandler: Broadcast via SSE

    Attributes:
        user_id: User importing file.
        provider_slug: Provider identifier.
        file_name: Original filename.
        file_format: File format.
        progress_percent: Progress percentage (0-100).
        records_processed: Number of records processed so far.
        total_records: Total records to process (may be estimate).
    """

    user_id: UUID
    provider_slug: str
    file_name: str
    file_format: str
    progress_percent: int
    records_processed: int
    total_records: int