AlphaLedgerDocs

Integration

Project Alpha integration

Connect two independent applications without sacrificing ownership, availability, or auditability.

AlphaLedger and Project Alpha remain independent applications with separate authentication and databases.

Ownership

  • AL owns time entries, breaks, employee pay rates, administrator approvals, corrections, and pay accrual snapshots.
  • PA owns clients, PA projects and assignments, invoices, customer payments, and pay-record payment status.
  • Internal AL projects never overwrite PA projects.
  • Foreign-owned conflicts are recorded; timestamps never silently select a winner.

Connection

During first-run setup, an operator may choose PA-assisted onboarding. AL verifies the PA manifest before creating the independent AL administrator, registers its callback, imports the initial change feed, and then requires administrator TOTP enrollment. Existing installations connect from Settings using password and TOTP reauthentication.

Suggested person matches use exact normalized email or exact normalized name only. An administrator must explicitly confirm every immutable PA person ID mapping. Credentials never synchronize, and a PA administrator can only map to an AL administrator.

Internal projects keep AL’s simple name, optional client, and optional code. PA-owned projects display the PA convention Client · Project [Code] without renaming internal records. Approval stores the displayed project name in the immutable time-entry snapshot, so later PA renames do not rewrite historical reports.

Reliability

Domain writes and outbox inserts share a transaction. The cron process retries indefinitely with exponential backoff and jitter capped at one hour. Ten failures surface a message as needing attention; five consecutive connection failures mark PA degraded. Authentication failures require administrator intervention.

Incoming events are stored before processing and deduplicated by installation/event ID. HMAC signatures cover timestamp + '.' + raw_body, and timestamps outside five minutes are rejected. Pull reconciliation runs after connection/recovery and at least every six hours.

When PA advertises operational_ledger_v1, every relevant AL domain transaction also queues a versioned ledger.* delta. The worker sends those records to /api/v1/integrations/alphaledger/ledger-records/batch within its normal one-minute cycle and sends a complete paginated snapshot on connection, recovery, and at least every six hours. PA may tombstone records missing from a snapshot only after the final snapshot page succeeds.

Operational batches require the dedicated PA bearer key plus X-AL-Timestamp and X-AL-Signature. The direction-bound HMAC covers the timestamp, method, exact path, and SHA-256 body hash. The mirror includes employee/link state, observed projects and assignments, every time-entry state, breaks, corrections, and pay accruals. It excludes sessions, login attempts, credentials, locks, integration queues, raw audit events, and IP addresses.

See docs/contracts/ and simulator/router.php for the PA-side implementation target.

Contract resources