# leoalvarenga404/bridge-flow architecture

> Architecture diagram of the GitHub repository leoalvarenga404/bridge-flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leoalvarenga404/bridge-flow
- Repository: https://github.com/leoalvarenga404/bridge-flow

## Overview

BridgeFlow accepts customer and order events asynchronously, normalizes them, records them for audit, and delivers them to a destination system. Failed deliveries are retried and can be manually reprocessed; the web panel provides event inspection and operational metrics. The README documents the broader queue and destination behavior; sampled source confirms the API, repository, and panel boundaries, but not every worker-to-queue wiring detail.

Main entry points: [`api/src/integration/application/receive-event.usecase.ts`](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/application/receive-event.usecase.ts) (Receive event), [`panel/lib/api.ts`](https://github.com/leoalvarenga404/bridge-flow/blob/main/panel/lib/api.ts) (API client), [`api/src/integration/infra/messaging/rabbitmq.consumer.ts`](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/messaging/rabbitmq.consumer.ts) (Queue consumer), [`api/src/integration/application/process-event.usecase.ts`](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/application/process-event.usecase.ts) (Process event)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Event intake"]
  node_integration_controller["Integration API"]
  node_receive_event["Receive event"]
  node_canonical["Canonical model<br/>[canonical.ts]"]
  node_event_repo["Event repository"]
end

subgraph group_delivery["Async delivery"]
  node_publisher["Queue publisher"]
  node_broker["RabbitMQ queues"]
  node_consumer["Queue consumer"]
  node_process_event["Process event"]
  node_message_handler["Message handler"]
  node_retry_policy["Retry policy<br/>[retry-policy.ts]"]
  node_destination_repo["Destination repository"]
end

subgraph group_audit["Audit and recovery"]
  node_event_store[("Audit store")]
  node_events_controller["Events API"]
  node_events_repo["Audit queries"]
  node_reprocess["Reprocess event"]
end

subgraph group_panel["Operations panel"]
  node_panel_pages["Event views<br/>[page.tsx]"]
  node_panel_detail["Event detail<br/>[page.tsx]"]
  node_panel_actions["Reprocess action<br/>[actions.ts]"]
  node_panel_api["API client<br/>[api.ts]"]
end

node_system_a(("System A"))
node_system_b[("System B records")]
node_operator(("Operator"))

node_system_a -->|"submits events"| node_integration_controller
node_integration_controller -->|"calls receive"| node_receive_event
node_receive_event -->|"normalizes payload"| node_canonical
node_receive_event -->|"creates event"| node_event_repo
node_event_repo -->|"writes audit"| node_event_store
node_receive_event -->|"publishes event"| node_publisher
node_publisher -->|"publishes message"| node_broker
node_broker -->|"delivers message"| node_consumer
node_consumer -->|"dispatches message"| node_message_handler
node_message_handler -->|"handles event"| node_process_event
node_process_event -->|"updates status"| node_event_repo
node_process_event -->|"loads destination"| node_destination_repo
node_destination_repo -->|"writes records"| node_system_b
node_consumer -->|"applies retries"| node_retry_policy
node_events_controller -->|"queries events"| node_events_repo
node_events_controller -->|"calls reprocess"| node_reprocess
node_events_repo -->|"reads and resets"| node_event_store
node_reprocess -->|"loads and resets"| node_events_repo
node_reprocess -->|"republishes event"| node_publisher
node_operator -->|"views events"| node_panel_pages
node_panel_pages -->|"fetches data"| node_panel_api
node_panel_detail -->|"fetches detail"| node_panel_api
node_operator -->|"requests reprocess"| node_panel_actions
node_panel_actions -->|"calls reprocess API"| node_panel_api
node_panel_api -->|"calls API"| node_events_controller

click node_integration_controller "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/http/integration.controller.ts"
click node_receive_event "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/application/receive-event.usecase.ts"
click node_canonical "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/domain/canonical.ts"
click node_event_repo "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/persistence/event.repository.ts"
click node_publisher "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/messaging/rabbitmq.publisher.ts"
click node_consumer "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/messaging/rabbitmq.consumer.ts"
click node_process_event "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/application/process-event.usecase.ts"
click node_message_handler "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/messaging/logging-message-handler.ts"
click node_retry_policy "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/domain/retry-policy.ts"
click node_destination_repo "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/persistence/destination.repository.ts"
click node_events_controller "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/events/http/events.controller.ts"
click node_events_repo "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/events/infra/prisma-events.repository.ts"
click node_reprocess "https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/events/application/reprocess-event.usecase.ts"
click node_panel_pages "https://github.com/leoalvarenga404/bridge-flow/blob/main/panel/app/events/page.tsx"
click node_panel_detail "https://github.com/leoalvarenga404/bridge-flow/blob/main/panel/app/events/%5Bid%5D/page.tsx"
click node_panel_actions "https://github.com/leoalvarenga404/bridge-flow/blob/main/panel/app/actions.ts"
click node_panel_api "https://github.com/leoalvarenga404/bridge-flow/blob/main/panel/lib/api.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_integration_controller,node_receive_event,node_canonical,node_event_repo toneBlue
class node_publisher,node_broker,node_consumer,node_process_event,node_message_handler,node_retry_policy,node_destination_repo,node_system_b toneAmber
class node_event_store,node_events_controller,node_events_repo,node_reprocess toneMint
class node_panel_pages,node_panel_detail,node_panel_actions,node_panel_api toneRose
class node_system_a,node_operator toneIndigo
```

## Components

### Event intake

- [Integration API](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/http/integration.controller.ts): `api/src/integration/http/integration.controller.ts`
- [Receive event](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/application/receive-event.usecase.ts): `api/src/integration/application/receive-event.usecase.ts`
- [Canonical model](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/domain/canonical.ts): `api/src/integration/domain/canonical.ts`
- [Event repository](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/persistence/event.repository.ts): `api/src/integration/infra/persistence/event.repository.ts`

### Async delivery

- [Queue publisher](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/messaging/rabbitmq.publisher.ts): `api/src/integration/infra/messaging/rabbitmq.publisher.ts`
- **RabbitMQ queues**
- [Queue consumer](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/messaging/rabbitmq.consumer.ts): `api/src/integration/infra/messaging/rabbitmq.consumer.ts`
- [Process event](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/application/process-event.usecase.ts): `api/src/integration/application/process-event.usecase.ts`
- [Message handler](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/messaging/logging-message-handler.ts): `api/src/integration/infra/messaging/logging-message-handler.ts`
- [Retry policy](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/domain/retry-policy.ts): `api/src/integration/domain/retry-policy.ts`
- [Destination repository](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/integration/infra/persistence/destination.repository.ts): `api/src/integration/infra/persistence/destination.repository.ts`

### Audit and recovery

- **Audit store**
- [Events API](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/events/http/events.controller.ts): `api/src/events/http/events.controller.ts`
- [Audit queries](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/events/infra/prisma-events.repository.ts): `api/src/events/infra/prisma-events.repository.ts`
- [Reprocess event](https://github.com/leoalvarenga404/bridge-flow/blob/main/api/src/events/application/reprocess-event.usecase.ts): `api/src/events/application/reprocess-event.usecase.ts`

### Operations panel

- [Event views](https://github.com/leoalvarenga404/bridge-flow/blob/main/panel/app/events/page.tsx): `panel/app/events/page.tsx`
- [Event detail](https://github.com/leoalvarenga404/bridge-flow/blob/main/panel/app/events/%5Bid%5D/page.tsx): `panel/app/events/[id]/page.tsx`
- [Reprocess action](https://github.com/leoalvarenga404/bridge-flow/blob/main/panel/app/actions.ts): `panel/app/actions.ts`
- [API client](https://github.com/leoalvarenga404/bridge-flow/blob/main/panel/lib/api.ts): `panel/lib/api.ts`

### Other components

- **System A**
- **System B records**
- **Operator**

## Connections

- System A → Integration API: submits events
- Integration API → Receive event: calls receive
- Receive event → Canonical model: normalizes payload
- Receive event → Event repository: creates event
- Event repository → Audit store: writes audit
- Receive event → Queue publisher: publishes event
- Queue publisher → RabbitMQ queues: publishes message
- RabbitMQ queues → Queue consumer: delivers message
- Queue consumer → Message handler: dispatches message
- Message handler → Process event: handles event
- Process event → Event repository: updates status
- Process event → Destination repository: loads destination
- Destination repository → System B records: writes records
- Queue consumer → Retry policy: applies retries
- Events API → Audit queries: queries events
- Events API → Reprocess event: calls reprocess
- Audit queries → Audit store: reads and resets
- Reprocess event → Audit queries: loads and resets
- Reprocess event → Queue publisher: republishes event
- Operator → Event views: views events
- Event views → API client: fetches data
- Event detail → API client: fetches detail
- Operator → Reprocess action: requests reprocess
- Reprocess action → API client: calls reprocess API
- API client → Events API: calls API