The Change Log

In aeppic, every change made to the system is tracked and accounted for through the changelog, a central part of its event-sourced architecture. This guarantees transparency, consistency, and a full history of every action, making aeppic a highly auditable system.

Why a Changelog?

Auditability

• Every change is recorded, ensuring that the who, what, and when of all modifications can be traced back.
• This supports compliance with regulations like GDPR or HIPAA and fosters trust in the system.

Event-Sourced Architecture

• Changes are treated as independent, append-only events stored in a write log.
• The read model is rebuilt from the changelog, ensuring consistency across the system.

Error Mitigation

• Even failed changes (e.g., due to data collisions) are logged, preserving the attempted operation for inspection and potential remediation.

How the Changelog Works

Write Pipeline

• Every change targets a single document, maintaining atomicity at the document level.
• The change enters the write pipeline, where:
  • It’s authenticated and validated.
  • The write processor checks the document’s current state and computes the change.

Logging the Change

• If the change is valid, it’s appended to the document’s changelog.
• Even if the change doesn’t modify the document due to collisions, it remains logged for future inspection.

Data Model Update

• The read model is updated based on the logged change.
• Subscribers (e.g., clients or services) are notified of the update.

Key Features in aeppic 4

Separation of Write and Read Models

• In aeppic 3, the write and read operations were tightly coupled:
  • Changes updated the in-memory data model immediately before being written to the log.
• In aeppic 4, changes are first written to the write log, ensuring:
  • Consistency and durability of the event log.
  • Decoupled processing of the read model, enabling scalability and fault tolerance.

Handling Collisions

• Changes that fail due to data collisions are logged but don’t modify the document.
• This ensures:
  • No valid data is discarded.
  • Business rules and other system components can inspect and act on the collision data.

Service-Specific Listening

• While most subscribers listen to updates from the read model, some services (e.g., monitoring or data transformation services) can directly subscribe to the write model.

Benefits of the Changelog

Complete History

• The changelog provides a full, chronological record of every modification.
• Enables replaying or debugging past events.

Transparency and Trust

• Auditors and administrators can trace every change, even failed ones.
• Failed changes offer insights into issues like insufficient permissions or data conflicts.

Scalability

• Decoupling the write and read models allows for distributed processing and custom projections into other systems.

Extensibility

• Services can opt into listening to the write log directly, enabling real-time processing of specific changes.

Example Use Case: Auditing Changes

Imagine a document that tracks project milestones. One day, a user edits the description of a milestone to reflect an updated project scope. This action is immediately recorded in the changelog, capturing not only the new and previous descriptions but also the identity of the user who made the change and the exact timestamp of when it occurred.

Later, as the project progresses, a business rule automatically updates the milestone’s status to “Completed” based on predefined conditions. This action, too, is logged in the changelog, ensuring that even automated updates remain fully auditable.

At some point, an auditor reviews the milestone’s history. With access to the changelog, they can trace every modification made to the document. They see who edited the milestone’s description, when the edits were made, and how the description changed. They also note the automatic status update triggered by the business rule, confirming the logic behind the change. Even failed attempts to modify the milestone are preserved in the log, ensuring a complete and transparent record of the document’s lifecycle.