# e-ugine/idempotent-ingestion-engine architecture

> Architecture diagram of the GitHub repository e-ugine/idempotent-ingestion-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/e-ugine/idempotent-ingestion-engine
- Repository: https://github.com/e-ugine/idempotent-ingestion-engine

## Overview

This is a FastAPI payment-ingestion API that accepts a payment intent once per account and idempotency key; it simulates charging and does not connect to a real payment processor. The workflow routes a validated request, derives an account identity from the bearer token, and invokes the idempotency service, which checks for key reuse or an in-flight request and returns a stored or fresh result. PostgreSQL’s account/key uniqueness constraint provides the concurrency guard. The README documents bounded polling and stale-request handling; source excerpts show these in the service. Authentication is only a token-shape check here, not external identity verification.

Main entry points: [`app/api/v1/payments.py`](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/api/v1/payments.py) (Payment Route), [`app/services/payment_service.py`](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/services/payment_service.py) (Idempotency Service), [`app/api/v1/router.py`](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/api/v1/router.py) (API Router), [`app/db/base.py`](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/db/base.py) (Engine and Sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["FastAPI App<br/>[main.py]"]
  node_router["API Router<br/>[router.py]"]
  node_payment_route["Payment Route<br/>[payments.py]"]
  node_request_schema["Payment Schemas<br/>[payment.py]"]
  node_identity["Account Identity<br/>[dependencies.py]"]
end

subgraph group_idempotency["Idempotency Processing"]
  node_service["Idempotency Service<br/>[payment_service.py]"]
end

subgraph group_persistence["Persistence"]
  node_settings["Database Settings<br/>[config.py]"]
  node_db_base["Engine and Sessions<br/>[base.py]"]
  node_key_model["Idempotency Record<br/>[idempotency_key.py]"]
  node_postgres[("PostgreSQL")]
end

node_client(("Client"))

node_client -->|"submits payment"| node_payment_route
node_app -->|"mounts routes"| node_router
node_router -->|"registers route"| node_payment_route
node_payment_route -->|"validates request"| node_request_schema
node_payment_route -->|"resolves account"| node_identity
node_payment_route -->|"gets session"| node_db_base
node_payment_route -->|"processes payment"| node_service
node_service -->|"builds response"| node_request_schema
node_db_base -->|"loads database URL"| node_settings
node_service -->|"reads and writes"| node_key_model
node_key_model -->|"maps unique-key table"| node_postgres

click node_app "https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/main.py"
click node_router "https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/api/v1/router.py"
click node_payment_route "https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/api/v1/payments.py"
click node_request_schema "https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/schemas/payment.py"
click node_identity "https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/dependencies.py"
click node_service "https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/services/payment_service.py"
click node_settings "https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/config.py"
click node_db_base "https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/db/base.py"
click node_key_model "https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/db/models/idempotency_key.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_app,node_router,node_payment_route,node_request_schema,node_identity,node_client toneBlue
class node_service toneAmber
class node_settings,node_db_base,node_key_model,node_postgres toneMint
```

## Components

### HTTP API

- [FastAPI App](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/main.py): `app/main.py`
- [API Router](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/api/v1/router.py): `app/api/v1/router.py`
- [Payment Route](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/api/v1/payments.py): `app/api/v1/payments.py`
- [Payment Schemas](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/schemas/payment.py): `app/schemas/payment.py`
- [Account Identity](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/dependencies.py): `app/dependencies.py`

### Idempotency Processing

- [Idempotency Service](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/services/payment_service.py): `app/services/payment_service.py`

### Persistence

- [Database Settings](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/config.py): `app/config.py`
- [Engine and Sessions](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/db/base.py): `app/db/base.py`
- [Idempotency Record](https://github.com/e-ugine/idempotent-ingestion-engine/blob/main/app/db/models/idempotency_key.py): `app/db/models/idempotency_key.py`
- **PostgreSQL**

### Other components

- **Client**

## Connections

- Client → Payment Route: submits payment (evidence: `README.md`)
- FastAPI App → API Router: mounts routes (evidence: `app/main.py`)
- API Router → Payment Route: registers route (evidence: `app/api/v1/router.py`)
- Payment Route → Payment Schemas: validates request (evidence: `app/api/v1/payments.py`)
- Payment Route → Account Identity: resolves account (evidence: `app/api/v1/payments.py`)
- Payment Route → Engine and Sessions: gets session
- Payment Route → Idempotency Service: processes payment (evidence: `app/api/v1/payments.py`)
- Idempotency Service → Payment Schemas: builds response (evidence: `app/services/payment_service.py`)
- Engine and Sessions → Database Settings: loads database URL (evidence: `app/db/base.py`)
- Idempotency Service → Idempotency Record: reads and writes (evidence: `app/services/payment_service.py`)
- Idempotency Record → PostgreSQL: maps unique-key table (evidence: `README.md`)
