# Sync Engine Onboarding Guide

Welcome to the Ferrite Systems sync engine. This document explains the core architecture so you can start contributing without needing to reverse-engineer the codebase.

## Core Principles
1. **Never lose a patient record.** Every operation must be idempotent.
2. **Boring and reliable.** We prefer simple, predictable behavior over clever optimizations.
3. **Postgres is the source of truth.** All state is persisted before any network calls.

## Architecture Overview
The sync engine is a Rust service that processes batches of HL7/FHIR messages. It uses a state machine to track the lifecycle of each record:
- `PENDING`: Message received, not yet processed.
- `PROCESSING`: Message is being transformed and validated.
- `COMPLETED`: Message successfully synced to the target system.
- `FAILED`: Message failed validation or sync; requires manual intervention or retry.

## Key Components
1. **Batch Processor**: Reads batches from Postgres and processes them in parallel.
2. **Transformer**: Converts HL7/FHIR messages into our internal schema.
3. **Sync Worker**: Sends transformed records to the target hospital system.
4. **Retry Manager**: Handles failed records with exponential backoff.

## Data Flow
1. Messages are ingested via the admin console or direct API.
2. They are stored in Postgres in the `incoming_messages` table.
3. The batch processor picks up batches and processes them.
4. Successful records are moved to the `synced_records` table.
5. Failed records are logged in the `failed_records` table for review.

## Testing
- Use the `mock_hl7_feed` module to generate test data.
- Run `cargo test` to execute the full test suite.
- Check the `test_logs` directory for detailed output.

## Common Pitfalls
- **Idempotency**: Always check if a record already exists before inserting.
- **Concurrency**: Use database locks to prevent race conditions.
- **Error Handling**: Log all errors with context; never swallow exceptions.

## Next Steps
- Review the `src/sync/` directory to understand the code structure.
- Run the test suite locally to verify your environment.
- Ask Marcus or Priya if you have questions about the state machine logic.