# donovan-nudrak/e_commerce architecture

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

- Interactive diagram: https://gitdiagram.com/donovan-nudrak/e_commerce
- Repository: https://github.com/donovan-nudrak/e_commerce

## Overview

Ecommerce API is a FastAPI service for customer shopping and administration. HTTP clients enter through the app, then use domain endpoints for account access, browsing, cart management, checkout, and order tracking; administrators also manage catalog and fulfillment. The documented order lifecycle reserves stock at creation and restores it on cancellation. The code follows router/service/repository/model layers, with PostgreSQL persistence, Redis-backed authentication tokens, and local image storage. Several service internals were not sampled, so those documented capabilities are shown without speculative internal call chains.

Main entry points: [`E_commerce/main.py`](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/main.py) (FastAPI app), [`E_commerce/app/api/v1/auth/router.py`](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/auth/router.py) (Auth routes), [`E_commerce/app/api/v1/auth/dependencies.py`](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/auth/dependencies.py) (Auth dependencies), [`E_commerce/app/repositories/customer_repository.py`](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/repositories/customer_repository.py) (Customer repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API entry points"]
  node_app["FastAPI app<br/>[main.py]"]
end

subgraph group_commerce["Shopping and orders"]
  node_catalog_api["Catalog routes<br/>[router.py]"]
  node_product_service["Product service<br/>[product_service.py]"]
  node_category_api["Category routes<br/>[router.py]"]
  node_category_service["Category service"]
  node_cart_api["Cart routes<br/>[router.py]"]
  node_cart_service["Cart service<br/>[cart_service.py]"]
  node_orders_api["Order routes<br/>[router.py]"]
  node_order_service["Order lifecycle<br/>[order_service.py]"]
  node_stock_service["Stock control<br/>[stock_service.py]"]
  node_address_api["Address routes<br/>[router.py]"]
  node_payment_api["Saved payments<br/>[router.py]"]
  node_payment_types_api["Payment types<br/>[router.py]"]
end

subgraph group_identity["Accounts and access"]
  node_auth_api["Auth routes<br/>[router.py]"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_auth_guard["Auth dependencies<br/>[dependencies.py]"]
  node_users_api["User routes<br/>[router.py]"]
  node_user_service["User service<br/>[user_service.py]"]
end

subgraph group_admin["Administration"]
  node_admin_api["Admin routes<br/>[router.py]"]
  node_admin_service["Admin service<br/>[admin_service.py]"]
end

subgraph group_platform["Persistence and integrations"]
  node_product_repo["Product repository"]
  node_customer_repo["Customer repository"]
  node_order_repo["Order repository"]
  node_cart_repo["Cart repository<br/>[cart_repository.py]"]
  node_database[("PostgreSQL<br/>[session.py]")]
  node_redis[("Redis tokens<br/>[redis.py]")]
  node_media[("Local media<br/>[storage.py]")]
end

node_client(("HTTP client"))

node_client -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_auth_api
node_app -->|"mounts routes"| node_users_api
node_app -->|"mounts routes"| node_catalog_api
node_app -->|"mounts routes"| node_category_api
node_app -->|"mounts routes"| node_cart_api
node_app -->|"mounts routes"| node_orders_api
node_app -->|"mounts routes"| node_address_api
node_app -->|"mounts routes"| node_payment_api
node_app -->|"mounts routes"| node_payment_types_api
node_app -->|"mounts routes"| node_admin_api
node_auth_api -->|"invokes"| node_auth_service
node_auth_api -->|"invokes"| node_user_service
node_auth_api -->|"gets client"| node_redis
node_auth_api -->|"uses dependency"| node_auth_guard
node_auth_service -->|"reads and writes"| node_customer_repo
node_auth_service -->|"stores tokens"| node_redis
node_auth_guard -->|"loads customer"| node_customer_repo
node_users_api -->|"invokes"| node_user_service
node_user_service -->|"uses repository"| node_customer_repo
node_catalog_api -->|"invokes"| node_product_service
node_product_service -->|"uses repository"| node_product_repo
node_product_service -->|"stores images"| node_media
node_category_api -->|"invokes"| node_category_service
node_cart_api -->|"invokes"| node_cart_service
node_cart_service -->|"uses repository"| node_cart_repo
node_cart_service -->|"checks products"| node_product_repo
node_orders_api -->|"invokes"| node_order_service
node_order_service -->|"reads cart"| node_cart_repo
node_order_service -->|"uses repository"| node_order_repo
node_order_service -->|"controls stock"| node_stock_service
node_address_api -->|"requires customer"| node_auth_guard
node_payment_api -->|"requires customer"| node_auth_guard
node_admin_api -->|"invokes"| node_admin_service
node_admin_api -->|"invokes"| node_category_service
node_admin_api -->|"requires admin"| node_auth_guard
node_admin_service -->|"uses repository"| node_customer_repo
node_admin_service -->|"uses repository"| node_order_repo
node_admin_service -->|"uses repository"| node_product_repo
node_customer_repo -.->|"queries database"| node_database
node_order_repo -.->|"queries database"| node_database
node_product_repo -.->|"queries database"| node_database
node_cart_repo -.->|"queries database"| node_database
node_app -->|"serves static files"| node_media

click node_app "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/main.py"
click node_auth_api "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/auth/router.py"
click node_auth_service "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/auth_service.py"
click node_auth_guard "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/auth/dependencies.py"
click node_users_api "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/users/router.py"
click node_user_service "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/user_service.py"
click node_catalog_api "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/products/router.py"
click node_product_service "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/product_service.py"
click node_product_repo "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/repositories/product_repository.py"
click node_category_api "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/categories/router.py"
click node_category_service "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/category_service.py"
click node_cart_api "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/cart/router.py"
click node_cart_service "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/cart_service.py"
click node_orders_api "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/orders/router.py"
click node_order_service "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/order_service.py"
click node_stock_service "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/stock_service.py"
click node_address_api "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/addresses/router.py"
click node_payment_api "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/payments/router.py"
click node_payment_types_api "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/payment_types/router.py"
click node_admin_api "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/admin/router.py"
click node_admin_service "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/admin_service.py"
click node_customer_repo "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/repositories/customer_repository.py"
click node_order_repo "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/repositories/order_repository.py"
click node_cart_repo "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/repositories/cart_repository.py"
click node_database "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/database/session.py"
click node_redis "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/core/redis.py"
click node_media "https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/utils/storage.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_client toneBlue
class node_catalog_api,node_product_service,node_category_api,node_category_service,node_cart_api,node_cart_service,node_orders_api,node_order_service,node_stock_service,node_address_api,node_payment_api,node_payment_types_api toneAmber
class node_auth_api,node_auth_service,node_auth_guard,node_users_api,node_user_service toneMint
class node_admin_api,node_admin_service toneRose
class node_product_repo,node_customer_repo,node_order_repo,node_cart_repo,node_database,node_redis,node_media toneIndigo
```

## Components

### API entry points

- [FastAPI app](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/main.py): `E_commerce/main.py`

### Shopping and orders

- [Catalog routes](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/products/router.py): `E_commerce/app/api/v1/products/router.py`
- [Product service](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/product_service.py): `E_commerce/app/services/product_service.py`
- [Category routes](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/categories/router.py): `E_commerce/app/api/v1/categories/router.py`
- [Category service](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/category_service.py): `E_commerce/app/services/category_service.py`
- [Cart routes](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/cart/router.py): `E_commerce/app/api/v1/cart/router.py`
- [Cart service](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/cart_service.py): `E_commerce/app/services/cart_service.py`
- [Order routes](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/orders/router.py): `E_commerce/app/api/v1/orders/router.py`
- [Order lifecycle](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/order_service.py): `E_commerce/app/services/order_service.py`
- [Stock control](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/stock_service.py): `E_commerce/app/services/stock_service.py`
- [Address routes](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/addresses/router.py): `E_commerce/app/api/v1/addresses/router.py`
- [Saved payments](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/payments/router.py): `E_commerce/app/api/v1/payments/router.py`
- [Payment types](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/payment_types/router.py): `E_commerce/app/api/v1/payment_types/router.py`

### Accounts and access

- [Auth routes](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/auth/router.py): `E_commerce/app/api/v1/auth/router.py`
- [Auth service](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/auth_service.py): `E_commerce/app/services/auth_service.py`
- [Auth dependencies](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/auth/dependencies.py): `E_commerce/app/api/v1/auth/dependencies.py`
- [User routes](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/users/router.py): `E_commerce/app/api/v1/users/router.py`
- [User service](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/user_service.py): `E_commerce/app/services/user_service.py`

### Administration

- [Admin routes](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/api/v1/admin/router.py): `E_commerce/app/api/v1/admin/router.py`
- [Admin service](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/services/admin_service.py): `E_commerce/app/services/admin_service.py`

### Persistence and integrations

- [Product repository](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/repositories/product_repository.py): `E_commerce/app/repositories/product_repository.py`
- [Customer repository](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/repositories/customer_repository.py): `E_commerce/app/repositories/customer_repository.py`
- [Order repository](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/repositories/order_repository.py): `E_commerce/app/repositories/order_repository.py`
- [Cart repository](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/repositories/cart_repository.py): `E_commerce/app/repositories/cart_repository.py`
- [PostgreSQL](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/database/session.py): `E_commerce/app/database/session.py`
- [Redis tokens](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/core/redis.py): `E_commerce/app/core/redis.py`
- [Local media](https://github.com/donovan-nudrak/e_commerce/blob/main/E_commerce/app/utils/storage.py): `E_commerce/app/utils/storage.py`

### Other components

- **HTTP client**

## Connections

- HTTP client → FastAPI app: sends requests
- FastAPI app → Auth routes: mounts routes (evidence: `E_commerce/main.py`)
- FastAPI app → User routes: mounts routes (evidence: `E_commerce/main.py`)
- FastAPI app → Catalog routes: mounts routes (evidence: `E_commerce/main.py`)
- FastAPI app → Category routes: mounts routes (evidence: `E_commerce/main.py`)
- FastAPI app → Cart routes: mounts routes (evidence: `E_commerce/main.py`)
- FastAPI app → Order routes: mounts routes (evidence: `E_commerce/main.py`)
- FastAPI app → Address routes: mounts routes (evidence: `E_commerce/main.py`)
- FastAPI app → Saved payments: mounts routes (evidence: `E_commerce/main.py`)
- FastAPI app → Payment types: mounts routes (evidence: `E_commerce/main.py`)
- FastAPI app → Admin routes: mounts routes (evidence: `E_commerce/main.py`)
- Auth routes → Auth service: invokes (evidence: `E_commerce/app/api/v1/auth/router.py`)
- Auth routes → User service: invokes (evidence: `E_commerce/app/api/v1/auth/router.py`)
- Auth routes → Redis tokens: gets client (evidence: `E_commerce/app/api/v1/auth/router.py`)
- Auth routes → Auth dependencies: uses dependency (evidence: `E_commerce/app/api/v1/auth/router.py`)
- Auth service → Customer repository: reads and writes (evidence: `E_commerce/app/services/auth_service.py`)
- Auth service → Redis tokens: stores tokens (evidence: `E_commerce/app/services/auth_service.py`)
- Auth dependencies → Customer repository: loads customer (evidence: `E_commerce/app/api/v1/auth/dependencies.py`)
- User routes → User service: invokes (evidence: `E_commerce/app/api/v1/users/router.py`)
- User service → Customer repository: uses repository (evidence: `E_commerce/app/services/user_service.py`)
- Catalog routes → Product service: invokes (evidence: `E_commerce/app/api/v1/products/router.py`)
- Product service → Product repository: uses repository (evidence: `E_commerce/app/services/product_service.py`)
- Product service → Local media: stores images (evidence: `E_commerce/app/services/product_service.py`)
- Category routes → Category service: invokes (evidence: `E_commerce/app/api/v1/categories/router.py`)
- Cart routes → Cart service: invokes (evidence: `E_commerce/app/api/v1/cart/router.py`)
- Cart service → Cart repository: uses repository (evidence: `E_commerce/app/services/cart_service.py`)
- Cart service → Product repository: checks products (evidence: `E_commerce/app/services/cart_service.py`)
- Order routes → Order lifecycle: invokes (evidence: `E_commerce/app/api/v1/orders/router.py`)
- Order lifecycle → Cart repository: reads cart (evidence: `E_commerce/app/services/order_service.py`)
- Order lifecycle → Order repository: uses repository (evidence: `E_commerce/app/services/order_service.py`)
- Order lifecycle → Stock control: controls stock (evidence: `E_commerce/app/services/order_service.py`)
- Address routes → Auth dependencies: requires customer (evidence: `E_commerce/app/api/v1/addresses/router.py`)
- Saved payments → Auth dependencies: requires customer (evidence: `E_commerce/app/api/v1/payments/router.py`)
- Admin routes → Admin service: invokes (evidence: `E_commerce/app/api/v1/admin/router.py`)
- Admin routes → Category service: invokes (evidence: `E_commerce/app/api/v1/admin/router.py`)
- Admin routes → Auth dependencies: requires admin (evidence: `E_commerce/app/api/v1/admin/router.py`)
- Admin service → Customer repository: uses repository (evidence: `E_commerce/app/services/admin_service.py`)
- Admin service → Order repository: uses repository (evidence: `E_commerce/app/services/admin_service.py`)
- Admin service → Product repository: uses repository (evidence: `E_commerce/app/services/admin_service.py`)
- Customer repository → PostgreSQL: queries database
- Order repository → PostgreSQL: queries database
- Product repository → PostgreSQL: queries database
- Cart repository → PostgreSQL: queries database
- FastAPI app → Local media: serves static files (evidence: `E_commerce/main.py`)
