# kachi72/ecommerce-back-end architecture

> Architecture diagram of the GitHub repository kachi72/ecommerce-back-end, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kachi72/ecommerce-back-end
- Repository: https://github.com/kachi72/ecommerce-back-end

## Overview

Ẹkúmidáyọ̀mí is a FastAPI backend for an ecommerce platform. The visible request path is an API client entering the application, which installs middleware and mounts health and versioned routes; health checks can probe PostgreSQL and Redis. Identity sessions use durable database state with Redis lookup hints. Other represented capabilities include audit recording, jobs, domain-event/outbox contracts, caching, and storage adapters. The README describes the product and local services but not domain endpoint coverage; several subsystem links therefore rely on SOURCE INDEX references, and unsampled wiring is omitted.

Main entry points: [`src/ekumidayomi/core/application.py`](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/application.py) (App lifecycle), [`src/ekumidayomi/auth/sessions.py`](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/auth/sessions.py) (Session service), [`src/ekumidayomi/db/base.py`](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/db/base.py) (ORM metadata), [`src/ekumidayomi/audit/service.py`](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/audit/service.py) (Audit service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application API"]
  node_app["App lifecycle<br/>[application.py]"]
  node_middleware["Request middleware<br/>[middleware.py]"]
  node_health["Health endpoints<br/>[health.py]"]
  node_v1["Versioned API<br/>[router.py]"]
end

subgraph group_identity["Identity and audit"]
  node_sessions["Session service<br/>[sessions.py]"]
  node_authsettings["Auth settings<br/>[settings.py]"]
  node_users["User model<br/>[model.py]"]
  node_audit["Audit service<br/>[service.py]"]
  node_auditmodel["Audit record<br/>[model.py]"]
end

subgraph group_data["Persistence"]
  node_database["Database lifecycle<br/>[session.py]"]
  node_uow["Unit of work<br/>[uow.py]"]
  node_orm["ORM metadata<br/>[base.py]"]
end

subgraph group_operations["Events and operations"]
  node_jobs["Job service<br/>[service.py]"]
  node_jobmodels["Job models<br/>[models.py]"]
  node_events["Domain events<br/>[events.py]"]
  node_outbox["Outbox repository<br/>[repository.py]"]
  node_outboxmodel["Outbox model<br/>[model.py]"]
end

subgraph group_foundation["Shared infrastructure"]
  node_cache["Cache client<br/>[client.py]"]
  node_codec["Cache codec<br/>[codec.py]"]
  node_storage["Memory storage<br/>[memory.py]"]
  node_storageports["Storage ports<br/>[ports.py]"]
  node_types["Shared value types<br/>[types.py]"]
  node_settings["App settings<br/>[settings.py]"]
  node_logging["Logging<br/>[logging.py]"]
  node_observability["Observability<br/>[observability.py]"]
end

node_client(("API client"))
node_postgres[("PostgreSQL")]
node_redis[("Redis")]

node_client -->|"sends requests"| node_app
node_app -->|"installs"| node_middleware
node_app -->|"mounts routes"| node_health
node_app -->|"mounts routes"| node_v1
node_app -->|"loads configuration"| node_settings
node_app -->|"creates and disposes"| node_database
node_app -->|"creates and closes"| node_redis
node_app -->|"configures"| node_logging
node_app -->|"initializes"| node_observability
node_middleware -->|"uses"| node_observability
node_health -->|"checks connection"| node_database
node_health -->|"checks connection"| node_redis
node_sessions -->|"uses settings"| node_authsettings
node_sessions -->|"validates user"| node_users
node_sessions -->|"queries and stages"| node_uow
node_sessions -->|"reads and invalidates hints"| node_redis
node_audit -->|"stages records"| node_auditmodel
node_audit -->|"uses transaction"| node_uow
node_database -->|"opens connections"| node_postgres
node_auditmodel -->|"maps from"| node_orm
node_users -->|"maps from"| node_orm
node_jobmodels -->|"maps from"| node_orm
node_outboxmodel -->|"maps from"| node_orm
node_cache -->|"encodes and decodes"| node_codec
node_jobs -->|"uses"| node_jobmodels
node_outbox -->|"persists"| node_outboxmodel
node_outbox -->|"serializes events"| node_events
node_outboxmodel -->|"stores event data"| node_events
node_storage -->|"implements"| node_storageports
node_jobs -->|"uses contracts"| node_types
node_audit -->|"uses contracts"| node_types
node_settings -->|"groups configuration"| node_authsettings
node_middleware -->|"uses"| node_logging

click node_app "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/application.py"
click node_middleware "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/api/middleware.py"
click node_health "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/api/health.py"
click node_v1 "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/api/v1/router.py"
click node_sessions "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/auth/sessions.py"
click node_authsettings "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/auth/settings.py"
click node_users "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/users/model.py"
click node_audit "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/audit/service.py"
click node_auditmodel "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/audit/model.py"
click node_database "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/db/session.py"
click node_uow "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/db/uow.py"
click node_orm "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/db/base.py"
click node_cache "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/cache/client.py"
click node_codec "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/cache/codec.py"
click node_jobs "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/jobs/service.py"
click node_jobmodels "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/jobs/models.py"
click node_events "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/events.py"
click node_outbox "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/outbox/repository.py"
click node_outboxmodel "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/outbox/model.py"
click node_storage "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/storage/memory.py"
click node_storageports "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/storage/ports.py"
click node_types "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/types.py"
click node_settings "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/settings.py"
click node_logging "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/logging.py"
click node_observability "https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/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_app,node_middleware,node_health,node_v1,node_client toneBlue
class node_sessions,node_authsettings,node_users,node_audit,node_auditmodel,node_postgres,node_redis toneAmber
class node_database,node_uow,node_orm toneMint
class node_jobs,node_jobmodels,node_events,node_outbox,node_outboxmodel toneRose
class node_cache,node_codec,node_storage,node_storageports,node_types,node_settings,node_logging,node_observability toneIndigo
```

## Components

### Application API

- [App lifecycle](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/application.py): `src/ekumidayomi/core/application.py`
- [Request middleware](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/api/middleware.py): `src/ekumidayomi/api/middleware.py`
- [Health endpoints](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/api/health.py): `src/ekumidayomi/api/health.py`
- [Versioned API](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/api/v1/router.py): `src/ekumidayomi/api/v1/router.py`

### Identity and audit

- [Session service](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/auth/sessions.py): `src/ekumidayomi/auth/sessions.py`
- [Auth settings](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/auth/settings.py): `src/ekumidayomi/auth/settings.py`
- [User model](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/users/model.py): `src/ekumidayomi/users/model.py`
- [Audit service](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/audit/service.py): `src/ekumidayomi/audit/service.py`
- [Audit record](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/audit/model.py): `src/ekumidayomi/audit/model.py`

### Persistence

- [Database lifecycle](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/db/session.py): `src/ekumidayomi/db/session.py`
- [Unit of work](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/db/uow.py): `src/ekumidayomi/db/uow.py`
- [ORM metadata](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/db/base.py): `src/ekumidayomi/db/base.py`

### Events and operations

- [Job service](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/jobs/service.py): `src/ekumidayomi/jobs/service.py`
- [Job models](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/jobs/models.py): `src/ekumidayomi/jobs/models.py`
- [Domain events](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/events.py): `src/ekumidayomi/events.py`
- [Outbox repository](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/outbox/repository.py): `src/ekumidayomi/outbox/repository.py`
- [Outbox model](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/outbox/model.py): `src/ekumidayomi/outbox/model.py`

### Shared infrastructure

- [Cache client](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/cache/client.py): `src/ekumidayomi/cache/client.py`
- [Cache codec](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/cache/codec.py): `src/ekumidayomi/cache/codec.py`
- [Memory storage](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/storage/memory.py): `src/ekumidayomi/storage/memory.py`
- [Storage ports](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/storage/ports.py): `src/ekumidayomi/storage/ports.py`
- [Shared value types](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/types.py): `src/ekumidayomi/core/types.py`
- [App settings](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/settings.py): `src/ekumidayomi/core/settings.py`
- [Logging](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/logging.py): `src/ekumidayomi/core/logging.py`
- [Observability](https://github.com/kachi72/ecommerce-back-end/blob/main/src/ekumidayomi/core/observability.py): `src/ekumidayomi/core/observability.py`

### Other components

- **API client**
- **PostgreSQL**
- **Redis**

## Connections

- API client → App lifecycle: sends requests (evidence: `README.md`)
- App lifecycle → Request middleware: installs (evidence: `src/ekumidayomi/core/application.py`)
- App lifecycle → Health endpoints: mounts routes (evidence: `src/ekumidayomi/core/application.py`)
- App lifecycle → Versioned API: mounts routes (evidence: `src/ekumidayomi/core/application.py`)
- App lifecycle → App settings: loads configuration (evidence: `src/ekumidayomi/core/application.py`)
- App lifecycle → Database lifecycle: creates and disposes (evidence: `src/ekumidayomi/core/application.py`)
- App lifecycle → Redis: creates and closes (evidence: `src/ekumidayomi/core/application.py`)
- App lifecycle → Logging: configures (evidence: `src/ekumidayomi/core/application.py`)
- App lifecycle → Observability: initializes (evidence: `src/ekumidayomi/core/application.py`)
- Request middleware → Observability: uses (evidence: `src/ekumidayomi/api/middleware.py`)
- Health endpoints → Database lifecycle: checks connection (evidence: `src/ekumidayomi/api/health.py`)
- Health endpoints → Redis: checks connection (evidence: `src/ekumidayomi/api/health.py`)
- Session service → Auth settings: uses settings (evidence: `src/ekumidayomi/auth/sessions.py`)
- Session service → User model: validates user (evidence: `src/ekumidayomi/auth/sessions.py`)
- Session service → Unit of work: queries and stages (evidence: `src/ekumidayomi/auth/sessions.py`)
- Session service → Redis: reads and invalidates hints (evidence: `src/ekumidayomi/auth/sessions.py`)
- Audit service → Audit record: stages records (evidence: `src/ekumidayomi/audit/service.py`)
- Audit service → Unit of work: uses transaction (evidence: `src/ekumidayomi/audit/service.py`)
- Database lifecycle → PostgreSQL: opens connections (evidence: `src/ekumidayomi/db/session.py`)
- Audit record → ORM metadata: maps from (evidence: `src/ekumidayomi/audit/model.py`)
- User model → ORM metadata: maps from (evidence: `src/ekumidayomi/users/model.py`)
- Job models → ORM metadata: maps from (evidence: `src/ekumidayomi/jobs/models.py`)
- Outbox model → ORM metadata: maps from (evidence: `src/ekumidayomi/outbox/model.py`)
- Cache client → Cache codec: encodes and decodes (evidence: `src/ekumidayomi/cache/client.py`)
- Job service → Job models: uses (evidence: `src/ekumidayomi/jobs/service.py`)
- Outbox repository → Outbox model: persists (evidence: `src/ekumidayomi/outbox/repository.py`)
- Outbox repository → Domain events: serializes events (evidence: `src/ekumidayomi/outbox/repository.py`)
- Outbox model → Domain events: stores event data (evidence: `src/ekumidayomi/outbox/model.py`)
- Memory storage → Storage ports: implements (evidence: `src/ekumidayomi/storage/memory.py`)
- Job service → Shared value types: uses contracts (evidence: `src/ekumidayomi/jobs/service.py`)
- Audit service → Shared value types: uses contracts (evidence: `src/ekumidayomi/audit/service.py`)
- App settings → Auth settings: groups configuration (evidence: `src/ekumidayomi/core/settings.py`)
- Request middleware → Logging: uses (evidence: `src/ekumidayomi/api/middleware.py`)
