> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/integrations/architecture.md).

# Architecture and sync lifecycle

Kangal uses a shared driver contract so providers behave consistently even when their authentication and APIs differ.

```
Kangal Console
     |
Integration API
     |
Encrypted config and secret references
     |
Redis Streams job queue (production) -> Integration worker -> Provider API
     |                                           |
Sync history, status, request ID, rate-limit and error metadata
```

## Configuration and secret handling

Provider configuration is tenant-scoped. Sensitive values are encrypted or resolved from a supported secret reference at execution time. API responses return masked values instead of stored plaintext credentials.

## Job lifecycle

1. The installation request validates the provider slug, tenant and optional resource scope, generic request envelope, and secret-source rules. It accepts either `secrets` or `secrets_ref`, but not both.
2. A manual sync request places a bounded job on the integration queue.
3. The worker resolves credentials and the provider driver validates its required fields and connectivity while running the manual sync.
4. The result is recorded in sync history and successful work is acknowledged.

## Queue backends

Production deployments must use `redis-streams` for durable integration sync delivery. With this backend, retryable failures use bounded retries, unacknowledged jobs are reclaimed after a worker interruption, and exhausted jobs move to the dead-letter stream.

The `memory` backend is the local development mode and keeps queued work in the application process.

## Normalized result metadata

Where supported by the provider, Kangal records:

* provider request or correlation ID;
* authentication and authorization failure category;
* rate-limit state and `Retry-After` guidance;
* network, timeout, TLS, and validation failure category;
* imported object counts and provider-specific summary metadata.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/integrations/architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.