# PhoenixMicro v1.0.0 - Table of Contents

> Production-grade microservices toolkit for Elixir/Phoenix — transports, sagas, RPC, schema registry, circuit breakers, outbox pattern, and more.

## Pages

- [Overview](readme.md)
- [Changelog](changelog.md)

- Guides
  - [Getting Started](getting_started.md)
  - [Transports](transports.md)
  - [Sagas & Compensation](sagas.md)
  - [Schema Registry](schemas.md)
  - [Middleware](middleware.md)
  - [RPC](rpc.md)
  - [Outbox Pattern](outbox.md)
  - [Testing](testing.md)
  - [Deployment & Production](deployment.md)

## Modules

- [PhoenixMicro.Application](PhoenixMicro.Application.md): OTP Application entry point for `phoenix_micro`.
- [PhoenixMicro.Consumer.RetryScheduler](PhoenixMicro.Consumer.RetryScheduler.md): Computes the next retry delay using exponential backoff with optional jitter.
- [PhoenixMicro.Consumer.Worker](PhoenixMicro.Consumer.Worker.md): GenServer that manages the lifecycle of a single consumer subscription:
subscribing to the transport, invoking the consumer module, and
applying retry + DLQ logic.

- [PhoenixMicro.Middleware.CircuitBreaker.Store](PhoenixMicro.Middleware.CircuitBreaker.Store.md): ETS-backed store for circuit breaker state.
- [PhoenixMicro.Middleware.Idempotency.ETSStore](PhoenixMicro.Middleware.Idempotency.ETSStore.md): ETS-backed idempotency store for development and testing.
- [PhoenixMicro.Outbox.Message](PhoenixMicro.Outbox.Message.md): Ecto schema for the `outbox_messages` table.
- [PhoenixMicro.Outbox.Relay](PhoenixMicro.Outbox.Relay.md): GenServer that polls the `outbox_messages` table and relays undelivered
messages to the configured transport.
- [PhoenixMicro.Pipeline](PhoenixMicro.Pipeline.md): A Broadway-backed message-processing pipeline for `PhoenixMicro.Consumer`.
- [PhoenixMicro.Saga.Server](PhoenixMicro.Saga.Server.md): GenServer that executes and coordinates a single saga run.

- [PhoenixMicro.Saga.Supervisor](PhoenixMicro.Saga.Supervisor.md): DynamicSupervisor that owns all running saga processes.
Each saga runs in its own isolated `Saga.Server` process.

- [PhoenixMicro.Serializer.JSON](PhoenixMicro.Serializer.JSON.md): Default JSON serializer using `Jason`.

- [PhoenixMicro.Serializer.PassThrough](PhoenixMicro.Serializer.PassThrough.md): No-op serializer — passes binaries through unchanged.
Useful for transports (e.g. gRPC) that handle serialization externally.

- [PhoenixMicro.Supervisor](PhoenixMicro.Supervisor.md): Root supervisor for the `phoenix_micro` OTP application.
- [PhoenixMicro.Supervisor.ConsumerManager](PhoenixMicro.Supervisor.ConsumerManager.md): DynamicSupervisor that manages all registered consumer worker processes.
Consumers are registered either:
1. Statically via `PhoenixMicro.register_consumer/1` at app start.
2. Dynamically at runtime via `PhoenixMicro.Supervisor.ConsumerManager.start_consumer/1`.

- [PhoenixMicro.Transport.BroadwayProducer](PhoenixMicro.Transport.BroadwayProducer.md): A GenStage `Producer` that bridges any `PhoenixMicro.Transport` into a
Broadway pipeline.
- [PhoenixMicro.Transport.ConnectionSupervisor](PhoenixMicro.Transport.ConnectionSupervisor.md): A `Supervisor` that owns a single transport's connection process and its
associated worker pool.

- Core
  - [PhoenixMicro](PhoenixMicro.md): PhoenixMicro — a production-grade microservices toolkit for Elixir/Phoenix.
  - [PhoenixMicro.Config](PhoenixMicro.Config.md): Centralised configuration loader and validator for `phoenix_micro`.
  - [PhoenixMicro.Consumer](PhoenixMicro.Consumer.md): DSL for defining topic consumers with concurrency control, retry logic, and middleware.
  - [PhoenixMicro.Message](PhoenixMicro.Message.md): The canonical message envelope for all inter-service communication.
  - [PhoenixMicro.Producer](PhoenixMicro.Producer.md): High-level message producer with batching, async fire-and-forget,
and sync-with-ack publishing.
  - [PhoenixMicro.RPC](PhoenixMicro.RPC.md): Request-response RPC over any configured transport.

- Transports
  - [PhoenixMicro.Transport](PhoenixMicro.Transport.md): The behaviour that every transport adapter must implement.
  - [PhoenixMicro.Transport.Kafka](PhoenixMicro.Transport.Kafka.md): Pure-Elixir Kafka transport for `phoenix_micro`.
  - [PhoenixMicro.Transport.Memory](PhoenixMicro.Transport.Memory.md): An in-process pub/sub transport backed by `Registry` and `GenServer`.
  - [PhoenixMicro.Transport.NATS](PhoenixMicro.Transport.NATS.md): NATS transport adapter using `Gnat`.
  - [PhoenixMicro.Transport.RabbitMQ](PhoenixMicro.Transport.RabbitMQ.md): RabbitMQ transport adapter using the `amqp` Hex package.
  - [PhoenixMicro.Transport.RedisStreams](PhoenixMicro.Transport.RedisStreams.md): Redis Streams transport adapter using `Redix`.

- Schema & Validation
  - [PhoenixMicro.Schema](PhoenixMicro.Schema.md): Typed message schema contracts with version negotiation and
backward-compatibility enforcement.
  - [PhoenixMicro.Schema.Field](PhoenixMicro.Schema.Field.md): Represents a single field definition in a `PhoenixMicro.Schema`.
  - [PhoenixMicro.Schema.Migrator](PhoenixMicro.Schema.Migrator.md): Version migration engine for `PhoenixMicro.Schema`.
  - [PhoenixMicro.Schema.Registry](PhoenixMicro.Schema.Registry.md): ETS-backed registry mapping topic names to their schema modules.
  - [PhoenixMicro.Schema.Validator](PhoenixMicro.Schema.Validator.md): Validation engine for `PhoenixMicro.Schema`.
  - [PhoenixMicro.Serializer](PhoenixMicro.Serializer.md): Behaviour for pluggable message serialization.

- Middleware
  - [PhoenixMicro.IdempotencyStore](PhoenixMicro.IdempotencyStore.md): Behaviour for idempotency stores.
  - [PhoenixMicro.Middleware](PhoenixMicro.Middleware.md): Behaviour for pluggable message-processing middleware.
  - [PhoenixMicro.Middleware.CircuitBreaker](PhoenixMicro.Middleware.CircuitBreaker.md): Circuit breaker middleware for consumer message handlers.
  - [PhoenixMicro.Middleware.Idempotency](PhoenixMicro.Middleware.Idempotency.md): Deduplication middleware. Checks whether a message ID has already been
successfully processed using a configured `PhoenixMicro.IdempotencyStore`.
  - [PhoenixMicro.Middleware.Logger](PhoenixMicro.Middleware.Logger.md): Logs message receipt and processing outcome at the `:debug` level.
Logs failures at the `:warning` level.

  - [PhoenixMicro.Middleware.Metrics](PhoenixMicro.Middleware.Metrics.md): Emits Telemetry span events for each message: `:start`, `:stop`, `:exception`.
Compatible with `Telemetry.Metrics` and `TelemetryMetricsStatsd` etc.

  - [PhoenixMicro.Middleware.Retry](PhoenixMicro.Middleware.Retry.md): Middleware-level retry with exponential backoff.
This is complementary to Consumer-level retry — use this when you want
to retry at the middleware layer (e.g. transient DB errors) before
propagating failure to the Consumer's retry logic.
  - [PhoenixMicro.Middleware.Tracing](PhoenixMicro.Middleware.Tracing.md): Distributed tracing middleware. Propagates trace context from message headers
and creates a span for each processed message.

- Sagas
  - [PhoenixMicro.Saga](PhoenixMicro.Saga.md): Compensation-based saga coordinator for distributed transactions.

- Outbox
  - [PhoenixMicro.Outbox](PhoenixMicro.Outbox.md): Transactional outbox pattern for guaranteed message delivery.

- Observability
  - [PhoenixMicro.LiveDashboard.Page](PhoenixMicro.LiveDashboard.Page.md): A `Phoenix.LiveDashboard` page that shows real-time PhoenixMicro metrics.
  - [PhoenixMicro.Phoenix.HealthPlug](PhoenixMicro.Phoenix.HealthPlug.md): A Plug that exposes a JSON health endpoint for `phoenix_micro`.
  - [PhoenixMicro.Phoenix.MetricsStore](PhoenixMicro.Phoenix.MetricsStore.md): In-process ring-buffer store for PhoenixMicro Telemetry metrics.
  - [PhoenixMicro.Telemetry](PhoenixMicro.Telemetry.md): Centralised Telemetry event definitions and emission helpers.

- Utilities
  - [PhoenixMicro.Utils.Backoff](PhoenixMicro.Utils.Backoff.md): Shared exponential backoff with optional full jitter.
  - [PhoenixMicro.Utils.Encoding](PhoenixMicro.Utils.Encoding.md): Shared encoding/decoding helpers used across transports and the producer.
  - [PhoenixMicro.Utils.ID](PhoenixMicro.Utils.ID.md): UUID v4 generation and correlation ID utilities.
  - [PhoenixMicro.Utils.WorkerPool](PhoenixMicro.Utils.WorkerPool.md): A lightweight bounded worker pool built on `Task.Supervisor`.

## Mix Tasks

- [mix phoenix_micro.gen.consumer](Mix.Tasks.PhoenixMicro.Gen.Consumer.md): Generates a PhoenixMicro consumer module with the correct DSL boilerplate.
- [mix phoenix_micro.gen.migration](Mix.Tasks.PhoenixMicro.Gen.Migration.md): Generates the `outbox_messages` table migration required by
`PhoenixMicro.Outbox`.
- [mix phoenix_micro.gen.saga](Mix.Tasks.PhoenixMicro.Gen.Saga.md): Generates a PhoenixMicro saga module with stub steps and compensations.
- [mix phoenix_micro.health](Mix.Tasks.PhoenixMicro.Health.md): Hits the PhoenixMicro health endpoint and prints a formatted status table.