| # IMATS ERP Integration Architecture | |
| This document specifies the integration architecture between the Collegiate Placement Engine and IMATS (Institutional Management & Academic Tracking System) or enterprise campus ERPs. | |
| --- | |
| ## 1. Architectural Pattern: Hexagonal Ports and Adapters | |
| The placement engine isolates external enterprise systems behind an explicit domain port: | |
| - **Port Interface**: [`backend.app.integrations.imats.interface.IIMATSClient`](backend/app/integrations/imats/interface.py) | |
| - **Production/Sandbox Adapter**: [`backend.app.integrations.imats.client.SandboxIMATSClient`](backend/app/integrations/imats/client.py) | |
| - **Offline Outbox Engine**: [`backend.app.integrations.imats.outbox.IMATSOutboxManager`](backend/app/integrations/imats/outbox.py) | |
| --- | |
| ## 2. Key Reliability Guarantees | |
| ### A. Idempotency Keys | |
| Every outbound sync operation (`push_shortlist`, `push_schedule`) requires an unguessable `idempotency_key`. The server and client deduplicate duplicate submissions, guaranteeing that network reconnects or retry storms never duplicate records or schedule slots. | |
| ### B. Exponential Backoff with Jitter | |
| When transient network interruptions occur across the college intranet, the client performs exponential backoff: | |
| $$\text{delay} = \text{initial\_backoff} \times 2^{\text{attempt}}$$ | |
| By default, the client makes 3 retry attempts before delegating to the offline outbox. | |
| ### C. Offline Outbox Pattern | |
| When the campus LAN is severed or the remote IMATS server is in a maintenance window: | |
| 1. Shortlists and schedules are persisted to the local outbox marked as `PENDING`. | |
| 2. When connectivity is re-established, the officer or background automation calls `/api/imats/sync` to flush pending items reliably. | |
| --- | |
| ## 3. How to Swap in the Live Production Endpoint | |
| To connect to a live institutional IMATS ERP instance: | |
| 1. Create a concrete class `LiveIMATSClient` implementing `IIMATSClient`: | |
| ```python | |
| import httpx | |
| from backend.app.integrations.imats.interface import IIMATSClient | |
| class LiveIMATSClient(IIMATSClient): | |
| def __init__(self, base_url: str, api_token: str): | |
| self.base_url = base_url | |
| self.headers = { | |
| "Authorization": f"Bearer {api_token}", | |
| "Content-Type": "application/json", | |
| } | |
| def push_shortlist(self, drive_id: str, student_ids: list[str], idempotency_key: str): | |
| resp = httpx.post( | |
| f"{self.base_url}/api/v1/drives/{drive_id}/shortlist", | |
| json={"student_ids": student_ids}, | |
| headers={**self.headers, "Idempotency-Key": idempotency_key}, | |
| timeout=15.0, | |
| ) | |
| resp.raise_for_status() | |
| return resp.json() | |
| ``` | |
| 2. Register the live adapter in `backend/app/api/main.py` using standard dependency injection: | |
| ```python | |
| imats_client = LiveIMATSClient( | |
| base_url=os.getenv("IMATS_BASE_URL", "https://imats.college.edu/api"), | |
| api_token=os.getenv("IMATS_API_TOKEN", "secret"), | |
| ) | |
| ``` | |