# mryamusa/fastapi-shipmentservice architecture

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

- Interactive diagram: https://gitdiagram.com/mryamusa/fastapi-shipmentservice
- Repository: https://github.com/mryamusa/fastapi-shipmentservice

## Overview

This is a FastAPI shipment-management API. Sellers create shipments, which are assigned to delivery partners and recorded with an initial timeline event; partners can update shipment progress, while sellers can retrieve or cancel shipments. Status events trigger customer email notifications. Seller and partner routes, authentication dependencies, persistence, and notification handling form supporting workflows. The sampled source shows shipment and seller route behavior; delivery-partner route details and several services were not sampled, so their internal behavior is not expanded.

Main entry points: [`app/api/routers/shipment.py`](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/routers/shipment.py) (Shipment routes), [`app/api/dependencies.py`](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/dependencies.py) (API dependencies), [`app/api/router.py`](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/router.py) (Master router), [`app/services/shipment.py`](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/shipment.py) (Shipment service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_app["FastAPI application<br/>[main.py]"]
  node_router["Master router<br/>[router.py]"]
  node_shipment_api["Shipment routes<br/>[shipment.py]"]
  node_seller_api["Seller routes<br/>[seller.py]"]
  node_partner_api["Partner routes"]
  node_dependencies["API dependencies<br/>[dependencies.py]"]
  node_security["Token security<br/>[security.py]"]
  node_utils["Token decoding<br/>[utils.py]"]
end

subgraph group_shipment["Shipment lifecycle"]
  node_shipment_service["Shipment service<br/>[shipment.py]"]
  node_event_service["Shipment events<br/>[shipment_event.py]"]
  node_shipment_schema["Shipment schemas<br/>[shipment.py]"]
end

subgraph group_accounts["Seller and partner"]
  node_seller_service["Seller service<br/>[seller.py]"]
  node_partner_service["Partner service"]
end

subgraph group_infra["Persistence and notifications"]
  node_models["Domain models<br/>[models.py]"]
  node_session["Database sessions<br/>[session.py]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Token blacklist<br/>[redis.py]")]
  node_notifications["Email notifications<br/>[notifications.py]"]
  node_templates["Email templates"]
end

node_seller(("Seller"))
node_partner(("Delivery partner"))
node_customer(("Shipment customer"))
node_smtp(("Email service"))

node_app -->|"creates tables"| node_session
node_app -->|"mounts routes"| node_router
node_router -->|"includes"| node_shipment_api
node_router -->|"includes"| node_seller_api
node_router -->|"includes"| node_partner_api
node_seller -->|"requests"| node_seller_api
node_partner -->|"requests"| node_partner_api
node_seller -->|"creates or cancels"| node_shipment_api
node_partner -->|"updates"| node_shipment_api
node_shipment_api -->|"invokes"| node_shipment_service
node_shipment_api -->|"validates"| node_shipment_schema
node_shipment_service -->|"assigns partner"| node_partner_service
node_shipment_service -->|"records events"| node_event_service
node_shipment_service -->|"creates shipment"| node_models
node_event_service -->|"creates event"| node_models
node_event_service -->|"sends status email"| node_notifications
node_notifications -->|"renders"| node_templates
node_notifications -->|"sends email"| node_smtp
node_customer -->|"receives updates"| node_notifications
node_seller_api -->|"invokes"| node_seller_service
node_seller_api -->|"blacklists token"| node_redis
node_dependencies -->|"uses schemes"| node_security
node_dependencies -->|"decodes token"| node_utils
node_dependencies -->|"checks blacklist"| node_redis
node_dependencies -->|"opens session"| node_session
node_session -->|"connects"| node_postgres

click node_app "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/main.py"
click node_router "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/router.py"
click node_shipment_api "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/routers/shipment.py"
click node_seller_api "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/routers/seller.py"
click node_partner_api "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/routers/delivery_partner.py"
click node_dependencies "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/dependencies.py"
click node_security "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/core/security.py"
click node_utils "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/utils.py"
click node_shipment_service "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/shipment.py"
click node_event_service "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/shipment_event.py"
click node_shipment_schema "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/schemas/shipment.py"
click node_seller_service "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/seller.py"
click node_partner_service "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/delivery_partner.py"
click node_models "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/database/models.py"
click node_session "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/database/session.py"
click node_redis "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/database/redis.py"
click node_notifications "https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/notifications.py"
click node_templates "https://github.com/mryamusa/fastapi-shipmentservice/tree/main/app/templates"

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_shipment_api,node_seller_api,node_partner_api,node_dependencies,node_security,node_utils toneBlue
class node_shipment_service,node_event_service,node_shipment_schema toneAmber
class node_seller_service,node_partner_service toneMint
class node_models,node_session,node_postgres,node_redis,node_notifications,node_templates toneRose
class node_seller,node_partner,node_customer,node_smtp toneIndigo
```

## Components

### API and identity

- [FastAPI application](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/main.py): `app/main.py`
- [Master router](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/router.py): `app/api/router.py`
- [Shipment routes](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/routers/shipment.py): `app/api/routers/shipment.py`
- [Seller routes](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/routers/seller.py): `app/api/routers/seller.py`
- [Partner routes](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/routers/delivery_partner.py): `app/api/routers/delivery_partner.py`
- [API dependencies](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/dependencies.py): `app/api/dependencies.py`
- [Token security](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/core/security.py): `app/core/security.py`
- [Token decoding](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/utils.py): `app/utils.py`

### Shipment lifecycle

- [Shipment service](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/shipment.py): `app/services/shipment.py`
- [Shipment events](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/shipment_event.py): `app/services/shipment_event.py`
- [Shipment schemas](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/api/schemas/shipment.py): `app/api/schemas/shipment.py`

### Seller and partner

- [Seller service](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/seller.py): `app/services/seller.py`
- [Partner service](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/delivery_partner.py): `app/services/delivery_partner.py`

### Persistence and notifications

- [Domain models](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/database/models.py): `app/database/models.py`
- [Database sessions](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/database/session.py): `app/database/session.py`
- **PostgreSQL**
- [Token blacklist](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/database/redis.py): `app/database/redis.py`
- [Email notifications](https://github.com/mryamusa/fastapi-shipmentservice/blob/main/app/services/notifications.py): `app/services/notifications.py`
- [Email templates](https://github.com/mryamusa/fastapi-shipmentservice/tree/main/app/templates): `app/templates`

### Other components

- **Seller**
- **Delivery partner**
- **Shipment customer**
- **Email service**

## Connections

- FastAPI application → Database sessions: creates tables
- FastAPI application → Master router: mounts routes
- Master router → Shipment routes: includes
- Master router → Seller routes: includes
- Master router → Partner routes: includes
- Seller → Seller routes: requests
- Delivery partner → Partner routes: requests
- Seller → Shipment routes: creates or cancels
- Delivery partner → Shipment routes: updates
- Shipment routes → Shipment service: invokes
- Shipment routes → Shipment schemas: validates
- Shipment service → Partner service: assigns partner
- Shipment service → Shipment events: records events
- Shipment service → Domain models: creates shipment
- Shipment events → Domain models: creates event
- Shipment events → Email notifications: sends status email
- Email notifications → Email templates: renders
- Email notifications → Email service: sends email
- Shipment customer → Email notifications: receives updates
- Seller routes → Seller service: invokes
- Seller routes → Token blacklist: blacklists token
- API dependencies → Token security: uses schemes
- API dependencies → Token decoding: decodes token
- API dependencies → Token blacklist: checks blacklist
- API dependencies → Database sessions: opens session
- Database sessions → PostgreSQL: connects