# parikshit06reddy-cloud/event-ledger architecture

> Architecture diagram of the GitHub repository parikshit06reddy-cloud/event-ledger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parikshit06reddy-cloud/event-ledger
- Repository: https://github.com/parikshit06reddy-cloud/event-ledger

## Overview

Event Ledger accepts financial events through a public Gateway, records them idempotently, and forwards transactions to an independent Account Service, which maintains materialized balances. Clients can also query chronological events and balances. When downstream writes fail, an optional outbox queues replay; the gateway’s balance proxy uses the same resilience client. The README documents tracing, health probes, metrics, and structured logging across both services. Some wiring is unsampled, so uncertain internal calls are omitted or marked unverified.

Main entry points: [`gateway/main.py`](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/main.py) (Event API), [`account_service/main.py`](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/main.py) (Transaction and Balance API), [`gateway/account_client.py`](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/account_client.py) (Account HTTP Client), [`gateway/outbox.py`](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/outbox.py) (Outbox Replay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Event Gateway"]
  node_gateway_app["Event API<br/>[main.py]"]
  node_gateway_models["Event Models<br/>[models.py]"]
  node_gateway_db[("Event and Outbox Store<br/>[database.py]")]
  node_gateway_errors["Error Handling<br/>[errors.py]"]
  node_rate_limit["Rate Limiting<br/>[rate_limit.py]"]
end

subgraph group_account["Account Service"]
  node_account_app["Transaction and Balance API<br/>[main.py]"]
  node_account_models["Transaction Models<br/>[models.py]"]
  node_account_db[("Account and Transaction Store<br/>[database.py]")]
  node_account_errors["Account Errors<br/>[errors.py]"]
end

subgraph group_resilience["Resilience and Delivery"]
  node_account_client["Account HTTP Client<br/>[account_client.py]"]
  node_outbox_worker["Outbox Replay<br/>[outbox.py]"]
end

subgraph group_telemetry["Observability"]
  node_gateway_metrics["Gateway Metrics<br/>[metrics.py]"]
  node_gateway_observability["Gateway Tracing and Logs<br/>[observability.py]"]
  node_account_metrics["Account Metrics<br/>[metrics.py]"]
  node_account_observability["Account Tracing and Logs<br/>[observability.py]"]
end

node_clients(("Upstream Clients"))
node_jaeger["Jaeger"]

node_clients -->|"submits events"| node_gateway_app
node_gateway_app -->|"reads and stores"| node_gateway_db
node_gateway_app -.->|"forwards transactions"| node_account_client
node_gateway_app -->|"proxies balance"| node_account_client
node_gateway_app -->|"enables fallback"| node_outbox_worker
node_outbox_worker -->|"reads and updates queue"| node_gateway_db
node_outbox_worker -->|"replays events"| node_account_client
node_account_client -->|"sends HTTP requests"| node_account_app
node_account_app -->|"applies and reads transactions"| node_account_db
node_gateway_app -.->|"validates events"| node_gateway_models
node_account_app -.->|"validates transactions"| node_account_models
node_gateway_app -.->|"checks requests"| node_rate_limit
node_gateway_app -.->|"formats errors"| node_gateway_errors
node_account_app -.->|"formats errors"| node_account_errors
node_gateway_app -.->|"exposes metrics"| node_gateway_metrics
node_account_app -->|"exposes metrics"| node_account_metrics
node_gateway_app -.->|"configures tracing"| node_gateway_observability
node_account_app -->|"configures tracing"| node_account_observability
node_gateway_observability -.->|"exports spans"| node_jaeger
node_account_observability -.->|"exports spans"| node_jaeger

click node_gateway_app "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/main.py"
click node_gateway_models "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/models.py"
click node_gateway_db "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/database.py"
click node_gateway_errors "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/errors.py"
click node_rate_limit "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/rate_limit.py"
click node_account_client "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/account_client.py"
click node_outbox_worker "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/outbox.py"
click node_account_app "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/main.py"
click node_account_models "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/models.py"
click node_account_db "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/database.py"
click node_account_errors "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/errors.py"
click node_gateway_metrics "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/metrics.py"
click node_gateway_observability "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/observability.py"
click node_account_metrics "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/metrics.py"
click node_account_observability "https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/observability.py"

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_gateway_app,node_gateway_models,node_gateway_db,node_gateway_errors,node_rate_limit,node_clients toneBlue
class node_account_app,node_account_models,node_account_db,node_account_errors toneAmber
class node_account_client,node_outbox_worker toneMint
class node_gateway_metrics,node_gateway_observability,node_account_metrics,node_account_observability toneRose
class node_jaeger toneIndigo
```

## Components

### Event Gateway

- [Event API](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/main.py): `gateway/main.py`
- [Event Models](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/models.py): `gateway/models.py`
- [Event and Outbox Store](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/database.py): `gateway/database.py`
- [Error Handling](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/errors.py): `gateway/errors.py`
- [Rate Limiting](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/rate_limit.py): `gateway/rate_limit.py`

### Account Service

- [Transaction and Balance API](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/main.py): `account_service/main.py`
- [Transaction Models](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/models.py): `account_service/models.py`
- [Account and Transaction Store](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/database.py): `account_service/database.py`
- [Account Errors](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/errors.py): `account_service/errors.py`

### Resilience and Delivery

- [Account HTTP Client](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/account_client.py): `gateway/account_client.py`
- [Outbox Replay](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/outbox.py): `gateway/outbox.py`

### Observability

- [Gateway Metrics](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/metrics.py): `gateway/metrics.py`
- [Gateway Tracing and Logs](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/gateway/observability.py): `gateway/observability.py`
- [Account Metrics](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/metrics.py): `account_service/metrics.py`
- [Account Tracing and Logs](https://github.com/parikshit06reddy-cloud/event-ledger/blob/main/account_service/observability.py): `account_service/observability.py`

### Other components

- **Upstream Clients**
- **Jaeger**

## Connections

- Upstream Clients → Event API: submits events (evidence: `README.md`)
- Event API → Event and Outbox Store: reads and stores (evidence: `gateway/main.py`)
- Event API → Account HTTP Client: forwards transactions (evidence: `gateway/main.py`)
- Event API → Account HTTP Client: proxies balance (evidence: `README.md`)
- Event API → Outbox Replay: enables fallback (evidence: `README.md`)
- Outbox Replay → Event and Outbox Store: reads and updates queue (evidence: `gateway/outbox.py`)
- Outbox Replay → Account HTTP Client: replays events (evidence: `gateway/outbox.py`)
- Account HTTP Client → Transaction and Balance API: sends HTTP requests (evidence: `gateway/account_client.py`)
- Transaction and Balance API → Account and Transaction Store: applies and reads transactions (evidence: `README.md`)
- Event API → Event Models: validates events (evidence: `gateway/main.py`)
- Transaction and Balance API → Transaction Models: validates transactions (evidence: `account_service/main.py`)
- Event API → Rate Limiting: checks requests (evidence: `gateway/main.py`)
- Event API → Error Handling: formats errors (evidence: `gateway/main.py`)
- Transaction and Balance API → Account Errors: formats errors (evidence: `account_service/main.py`)
- Event API → Gateway Metrics: exposes metrics (evidence: `gateway/main.py`)
- Transaction and Balance API → Account Metrics: exposes metrics (evidence: `account_service/main.py`)
- Event API → Gateway Tracing and Logs: configures tracing (evidence: `gateway/main.py`)
- Transaction and Balance API → Account Tracing and Logs: configures tracing (evidence: `account_service/main.py`)
- Gateway Tracing and Logs → Jaeger: exports spans (evidence: `README.md`)
- Account Tracing and Logs → Jaeger: exports spans (evidence: `README.md`)