# mus1eh/auctionapi architecture

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

- Interactive diagram: https://gitdiagram.com/mus1eh/auctionapi
- Repository: https://github.com/mus1eh/auctionapi

## Overview

Auction API supports account and role management, product listing and admin approval, timed bidding, owner decisions, CSV imports, and queued email notifications; a React frontend drives those workflows through the REST API. The principal path is marketplace user → API → product approval/listing → bids → scheduled auction closure and owner decision → email outbox delivery. Edges reflect the README, source-index references, and shown excerpts; unsampled service and frontend internals limit finer call-level links.

Main entry points: [`app/worker/tasks.py`](https://github.com/mus1eh/auctionapi/blob/main/app/worker/tasks.py) (Scheduled tasks), [`app/routers`](https://github.com/mus1eh/auctionapi/tree/main/app/routers) (API routes), [`app/repositories/product.py`](https://github.com/mus1eh/auctionapi/blob/main/app/repositories/product.py) (Product repository), [`app/core/database.py`](https://github.com/mus1eh/auctionapi/blob/main/app/core/database.py) (PostgreSQL database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Auction frontend"]
  node_webapp["Marketplace UI<br/>[App.tsx]"]
  node_web_auth["Session handling<br/>[AuthProvider.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["REST API"]
  node_api_entry["FastAPI application<br/>[main.py]"]
  node_routes["API routes"]
end

subgraph group_domain["Auction workflows"]
  node_auth_flow["Authentication"]
  node_product_flow["Product lifecycle"]
  node_bid_flow["Bidding decisions"]
  node_admin_flow["Admin actions"]
  node_auction_close["Auction closure<br/>[close.py]"]
end

subgraph group_data["Persistence"]
  node_models["Domain records"]
  node_product_repo["Product repository<br/>[product.py]"]
  node_bid_repo["Bid repository<br/>[bids.py]"]
  node_auth_repo["Auth repository<br/>[authentication.py]"]
  node_outbox_repo["Email outbox repository<br/>[email_outbox.py]"]
  node_database[("PostgreSQL database<br/>[database.py]")]
end

subgraph group_jobs["Background delivery"]
  node_celery["Celery worker and beat<br/>[celery_app.py]"]
  node_tasks["Scheduled tasks<br/>[tasks.py]"]
  node_mailer["SMTP mailer<br/>[service.py]"]
end

node_user(("Marketplace user"))
node_smtp(("SMTP service"))

node_user -->|"uses"| node_webapp
node_webapp -->|"requests through"| node_api_client
node_web_auth -->|"manages session"| node_api_client
node_api_client -->|"calls REST API"| node_routes
node_api_entry -->|"registers"| node_routes
node_routes -->|"invokes"| node_auth_flow
node_routes -->|"invokes"| node_product_flow
node_routes -->|"serves admin actions"| node_admin_flow
node_product_flow -->|"uses"| node_product_repo
node_bid_flow -->|"reads and locks"| node_product_repo
node_bid_flow -->|"uses"| node_bid_repo
node_bid_flow -->|"queues notices"| node_outbox_repo
node_tasks -->|"closes auctions"| node_auction_close
node_tasks -->|"locks expired products"| node_product_repo
node_tasks -->|"loads bids"| node_bid_repo
node_tasks -->|"processes outbox"| node_outbox_repo
node_tasks -->|"sends queued email"| node_mailer
node_mailer -->|"sends mail"| node_smtp
node_celery -->|"runs scheduled tasks"| node_tasks
node_product_repo -->|"queries and writes"| node_database
node_auth_repo -->|"stores tokens"| node_database
node_outbox_repo -->|"stores email queue"| node_database
node_models -->|"maps records"| node_database
node_auth_flow -->|"uses"| node_auth_repo

click node_webapp "https://github.com/mus1eh/auctionapi/blob/main/frontend/src/App.tsx"
click node_web_auth "https://github.com/mus1eh/auctionapi/blob/main/frontend/src/auth/AuthProvider.tsx"
click node_api_client "https://github.com/mus1eh/auctionapi/blob/main/frontend/src/api/client.ts"
click node_api_entry "https://github.com/mus1eh/auctionapi/blob/main/app/main.py"
click node_routes "https://github.com/mus1eh/auctionapi/tree/main/app/routers"
click node_auth_flow "https://github.com/mus1eh/auctionapi/tree/main/app/services/authentication"
click node_product_flow "https://github.com/mus1eh/auctionapi/tree/main/app/services/products"
click node_bid_flow "https://github.com/mus1eh/auctionapi/tree/main/app/services/bids"
click node_admin_flow "https://github.com/mus1eh/auctionapi/tree/main/app/services/admin"
click node_auction_close "https://github.com/mus1eh/auctionapi/blob/main/app/services/auctions/close.py"
click node_models "https://github.com/mus1eh/auctionapi/tree/main/app/models"
click node_product_repo "https://github.com/mus1eh/auctionapi/blob/main/app/repositories/product.py"
click node_bid_repo "https://github.com/mus1eh/auctionapi/blob/main/app/repositories/bids.py"
click node_auth_repo "https://github.com/mus1eh/auctionapi/blob/main/app/repositories/authentication.py"
click node_outbox_repo "https://github.com/mus1eh/auctionapi/blob/main/app/repositories/email_outbox.py"
click node_database "https://github.com/mus1eh/auctionapi/blob/main/app/core/database.py"
click node_celery "https://github.com/mus1eh/auctionapi/blob/main/app/worker/celery_app.py"
click node_tasks "https://github.com/mus1eh/auctionapi/blob/main/app/worker/tasks.py"
click node_mailer "https://github.com/mus1eh/auctionapi/blob/main/app/mailer/service.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_webapp,node_web_auth,node_api_client,node_user toneBlue
class node_api_entry,node_routes toneAmber
class node_auth_flow,node_product_flow,node_bid_flow,node_admin_flow,node_auction_close toneMint
class node_models,node_product_repo,node_bid_repo,node_auth_repo,node_outbox_repo,node_database toneRose
class node_celery,node_tasks,node_mailer,node_smtp toneIndigo
```

## Components

### Auction frontend

- [Marketplace UI](https://github.com/mus1eh/auctionapi/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Session handling](https://github.com/mus1eh/auctionapi/blob/main/frontend/src/auth/AuthProvider.tsx): `frontend/src/auth/AuthProvider.tsx`
- [API client](https://github.com/mus1eh/auctionapi/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### REST API

- [FastAPI application](https://github.com/mus1eh/auctionapi/blob/main/app/main.py): `app/main.py`
- [API routes](https://github.com/mus1eh/auctionapi/tree/main/app/routers): `app/routers`

### Auction workflows

- [Authentication](https://github.com/mus1eh/auctionapi/tree/main/app/services/authentication): `app/services/authentication`
- [Product lifecycle](https://github.com/mus1eh/auctionapi/tree/main/app/services/products): `app/services/products`
- [Bidding decisions](https://github.com/mus1eh/auctionapi/tree/main/app/services/bids): `app/services/bids`
- [Admin actions](https://github.com/mus1eh/auctionapi/tree/main/app/services/admin): `app/services/admin`
- [Auction closure](https://github.com/mus1eh/auctionapi/blob/main/app/services/auctions/close.py): `app/services/auctions/close.py`

### Persistence

- [Domain records](https://github.com/mus1eh/auctionapi/tree/main/app/models): `app/models`
- [Product repository](https://github.com/mus1eh/auctionapi/blob/main/app/repositories/product.py): `app/repositories/product.py`
- [Bid repository](https://github.com/mus1eh/auctionapi/blob/main/app/repositories/bids.py): `app/repositories/bids.py`
- [Auth repository](https://github.com/mus1eh/auctionapi/blob/main/app/repositories/authentication.py): `app/repositories/authentication.py`
- [Email outbox repository](https://github.com/mus1eh/auctionapi/blob/main/app/repositories/email_outbox.py): `app/repositories/email_outbox.py`
- [PostgreSQL database](https://github.com/mus1eh/auctionapi/blob/main/app/core/database.py): `app/core/database.py`

### Background delivery

- [Celery worker and beat](https://github.com/mus1eh/auctionapi/blob/main/app/worker/celery_app.py): `app/worker/celery_app.py`
- [Scheduled tasks](https://github.com/mus1eh/auctionapi/blob/main/app/worker/tasks.py): `app/worker/tasks.py`
- [SMTP mailer](https://github.com/mus1eh/auctionapi/blob/main/app/mailer/service.py): `app/mailer/service.py`

### Other components

- **Marketplace user**
- **SMTP service**

## Connections

- Marketplace user → Marketplace UI: uses (evidence: `README.md`)
- Marketplace UI → API client: requests through (evidence: `frontend/src/App.tsx`)
- Session handling → API client: manages session (evidence: `frontend/src/auth/AuthProvider.tsx`)
- API client → API routes: calls REST API (evidence: `README.md`)
- FastAPI application → API routes: registers (evidence: `app/main.py`)
- API routes → Authentication: invokes (evidence: `app/routers/authentication.py`)
- API routes → Product lifecycle: invokes (evidence: `app/routers/product.py`)
- API routes → Admin actions: serves admin actions (evidence: `app/routers/admin.py`)
- Product lifecycle → Product repository: uses (evidence: `app/services/products/csv.py`)
- Bidding decisions → Product repository: reads and locks (evidence: `app/services/bids/approvebid.py`)
- Bidding decisions → Bid repository: uses (evidence: `app/services/bids/approvebid.py`)
- Bidding decisions → Email outbox repository: queues notices (evidence: `app/services/bids/approvebid.py`)
- Scheduled tasks → Auction closure: closes auctions (evidence: `app/worker/tasks.py`)
- Scheduled tasks → Product repository: locks expired products (evidence: `app/worker/tasks.py`)
- Scheduled tasks → Bid repository: loads bids (evidence: `app/worker/tasks.py`)
- Scheduled tasks → Email outbox repository: processes outbox (evidence: `app/worker/tasks.py`)
- Scheduled tasks → SMTP mailer: sends queued email (evidence: `app/worker/tasks.py`)
- SMTP mailer → SMTP service: sends mail (evidence: `README.md`)
- Celery worker and beat → Scheduled tasks: runs scheduled tasks (evidence: `app/worker/tasks.py`)
- Product repository → PostgreSQL database: queries and writes (evidence: `app/repositories/product.py`)
- Auth repository → PostgreSQL database: stores tokens (evidence: `app/repositories/authentication.py`)
- Email outbox repository → PostgreSQL database: stores email queue (evidence: `app/worker/tasks.py`)
- Domain records → PostgreSQL database: maps records (evidence: `app/models/__init__.py`)
- Authentication → Auth repository: uses (evidence: `app/services/authentication/login.py`)
