# Integration Architecture

## Inter-Service Channels

Only these channels are allowed ([ADR-001](adr/ADR-001.md)):

1. Versioned REST API
2. Webhook
3. Async Event (message bus / outbox worker)
4. Outbox/Inbox pattern

## Internal Auth

Services authenticate with **Internal Service Tokens** (hashed in `internal_service_tokens`, scoped).

## External Providers

External systems (SMS, payment, storage, tax) integrate through provider adapters registered in [provider-registry.md](../provider-registry.md). Modules must not hardcode vendor SDKs into domain services without a provider boundary.

### Current known providers

| Provider | Use |
| --- | --- |
| Payamak | SMS OTP |
| Keycloak | IdP / SSO |
| Let's Encrypt + Certbot | TLS certificates |
| S3-compatible (planned) | File storage |

## BFF Pattern

Identity & Access acts as BFF for OIDC token exchange and Keycloak theme handoff so browser secrets stay constrained.

## Frontend Integration

Frontend uses typed API clients (`lib/api.ts` primary; `lib/api-client.ts` may exist for narrower helpers). Never call databases from the browser.

## Related Documents

- [Event-Driven Architecture](event-driven-architecture.md)
- [Provider Registry](../provider-registry.md)
- [Provider Reference](../reference/provider-reference.md)
- [Services Contracts](../reference/services-contracts.md)