# jkutkut/shoplist architecture

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

- Interactive diagram: https://gitdiagram.com/jkutkut/shoplist
- Repository: https://github.com/jkutkut/shoplist

## Overview

ShopList is a web application for managing shopping lists, products, and teams. Users interact with the frontend to manage products and team membership, while the frontend’s versioned API services send requests through a shared HTTP client to the Rust API. The backend also runs a separate gRPC authentication service backed by PostgreSQL. The sampled sources establish frontend request flow and service startup, but do not show route-to-storage calls or the internal authentication RPC implementation, so those links are omitted.

Main entry points: [`backend/api/src/route_handler.rs`](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/route_handler.rs) (Route assembly), [`backend/api/src/main.rs`](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/main.rs) (API startup), [`front/src/api/client.ts`](https://github.com/jkutkut/shoplist/blob/main/front/src/api/client.ts) (HTTP client), [`backend/auth/src/main.rs`](https://github.com/jkutkut/shoplist/blob/main/backend/auth/src/main.rs) (Auth service startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_product_ui["Product manager<br/>[ProductManager.tsx]"]
  node_list_state["List context<br/>[ListContext.tsx]"]
  node_list_view["List interface<br/>[ListLayout.tsx]"]
  node_team_ui["Team administration"]
  node_user_service["User service<br/>[userService.ts]"]
  node_team_service["Team service<br/>[teamService.ts]"]
  node_product_service["Product service<br/>[productService.ts]"]
  node_http_client["HTTP client<br/>[client.ts]"]
  node_fetch_transport["Fetch transport<br/>[fetchTransport.ts]"]
end

subgraph group_api["HTTP API"]
  node_api_start["API startup<br/>[main.rs]"]
  node_route_builder["Route assembly<br/>[route_handler.rs]"]
  node_user_routes["User routes<br/>[mod.rs]"]
  node_team_routes["Team routes<br/>[mod.rs]"]
  node_product_routes["Product routes<br/>[mod.rs]"]
  node_list_routes["List routes<br/>[mod.rs]"]
  node_category_routes["Category routes<br/>[mod.rs]"]
end

subgraph group_auth["Authentication"]
  node_auth_rpc["Auth RPC contract<br/>[auth.proto]"]
  node_auth_start["Auth service startup<br/>[main.rs]"]
  node_auth_db["Auth database adapter<br/>[db.rs]"]
end

subgraph group_state["Persistence"]
  node_postgres[("PostgreSQL")]
  node_api_db["API database adapter<br/>[mod.rs]"]
  node_api_cache["API cache<br/>[mod.rs]"]
end

node_user(("Shopper"))
node_auth_user(("Account user"))

node_user -->|"manages products"| node_product_ui
node_user -->|"manages lists"| node_list_view
node_user -->|"administers team"| node_team_ui
node_product_ui -->|"creates updates deletes"| node_product_service
node_team_ui -->|"requests membership"| node_team_service
node_user_service -->|"sends requests"| node_http_client
node_team_service -->|"sends requests"| node_http_client
node_product_service -->|"sends requests"| node_http_client
node_http_client -->|"dispatches HTTP"| node_fetch_transport
node_fetch_transport -->|"HTTP requests"| node_api_start
node_api_start -->|"connects database"| node_api_db
node_api_start -->|"initializes cache"| node_api_cache
node_api_start -->|"mounts routes"| node_route_builder
node_route_builder -->|"assembles routes"| node_user_routes
node_route_builder -->|"assembles routes"| node_team_routes
node_route_builder -->|"assembles routes"| node_product_routes
node_route_builder -->|"assembles routes"| node_list_routes
node_route_builder -->|"assembles routes"| node_category_routes
node_auth_start -->|"constructs adapter"| node_auth_db
node_auth_start -->|"serves contract"| node_auth_rpc
node_auth_start -->|"connects database"| node_postgres
node_auth_user -->|"account requests"| node_user_service
node_list_view -->|"reads list state"| node_list_state

click node_product_ui "https://github.com/jkutkut/shoplist/blob/main/front/src/components/product/ProductManager.tsx"
click node_list_state "https://github.com/jkutkut/shoplist/blob/main/front/src/context/ListContext.tsx"
click node_list_view "https://github.com/jkutkut/shoplist/blob/main/front/src/components/list/ListLayout.tsx"
click node_team_ui "https://github.com/jkutkut/shoplist/blob/main/front/src/components/config/MembersAdministration.tsx"
click node_user_service "https://github.com/jkutkut/shoplist/blob/main/front/src/api/versions/v1/userService.ts"
click node_team_service "https://github.com/jkutkut/shoplist/blob/main/front/src/api/versions/v1/teamService.ts"
click node_product_service "https://github.com/jkutkut/shoplist/blob/main/front/src/api/versions/v1/productService.ts"
click node_http_client "https://github.com/jkutkut/shoplist/blob/main/front/src/api/client.ts"
click node_fetch_transport "https://github.com/jkutkut/shoplist/blob/main/front/src/api/transport/fetchTransport.ts"
click node_api_start "https://github.com/jkutkut/shoplist/blob/main/backend/api/src/main.rs"
click node_route_builder "https://github.com/jkutkut/shoplist/blob/main/backend/api/src/route_handler.rs"
click node_user_routes "https://github.com/jkutkut/shoplist/blob/main/backend/api/src/routes/user/mod.rs"
click node_team_routes "https://github.com/jkutkut/shoplist/blob/main/backend/api/src/routes/team/mod.rs"
click node_product_routes "https://github.com/jkutkut/shoplist/blob/main/backend/api/src/routes/product/mod.rs"
click node_list_routes "https://github.com/jkutkut/shoplist/blob/main/backend/api/src/routes/list/mod.rs"
click node_category_routes "https://github.com/jkutkut/shoplist/blob/main/backend/api/src/routes/category/mod.rs"
click node_auth_rpc "https://github.com/jkutkut/shoplist/blob/main/proto/auth.proto"
click node_auth_start "https://github.com/jkutkut/shoplist/blob/main/backend/auth/src/main.rs"
click node_auth_db "https://github.com/jkutkut/shoplist/blob/main/backend/auth/src/db.rs"
click node_api_db "https://github.com/jkutkut/shoplist/blob/main/backend/api/src/db/mod.rs"
click node_api_cache "https://github.com/jkutkut/shoplist/blob/main/backend/api/src/cache/mod.rs"

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_product_ui,node_list_state,node_list_view,node_team_ui,node_user_service,node_team_service,node_product_service,node_http_client,node_fetch_transport,node_auth_user toneBlue
class node_api_start,node_route_builder,node_user_routes,node_team_routes,node_product_routes,node_list_routes,node_category_routes toneAmber
class node_auth_rpc,node_auth_start,node_auth_db toneMint
class node_postgres,node_api_db,node_api_cache toneRose
class node_user toneIndigo
```

## Components

### Web interface

- [Product manager](https://github.com/jkutkut/shoplist/blob/main/front/src/components/product/ProductManager.tsx): `front/src/components/product/ProductManager.tsx`
- [List context](https://github.com/jkutkut/shoplist/blob/main/front/src/context/ListContext.tsx): `front/src/context/ListContext.tsx`
- [List interface](https://github.com/jkutkut/shoplist/blob/main/front/src/components/list/ListLayout.tsx): `front/src/components/list/ListLayout.tsx`
- [Team administration](https://github.com/jkutkut/shoplist/blob/main/front/src/components/config/MembersAdministration.tsx): `front/src/components/config/MembersAdministration.tsx`
- [User service](https://github.com/jkutkut/shoplist/blob/main/front/src/api/versions/v1/userService.ts): `front/src/api/versions/v1/userService.ts`
- [Team service](https://github.com/jkutkut/shoplist/blob/main/front/src/api/versions/v1/teamService.ts): `front/src/api/versions/v1/teamService.ts`
- [Product service](https://github.com/jkutkut/shoplist/blob/main/front/src/api/versions/v1/productService.ts): `front/src/api/versions/v1/productService.ts`
- [HTTP client](https://github.com/jkutkut/shoplist/blob/main/front/src/api/client.ts): `front/src/api/client.ts`
- [Fetch transport](https://github.com/jkutkut/shoplist/blob/main/front/src/api/transport/fetchTransport.ts): `front/src/api/transport/fetchTransport.ts`

### HTTP API

- [API startup](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/main.rs): `backend/api/src/main.rs`
- [Route assembly](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/route_handler.rs): `backend/api/src/route_handler.rs`
- [User routes](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/routes/user/mod.rs): `backend/api/src/routes/user/mod.rs`
- [Team routes](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/routes/team/mod.rs): `backend/api/src/routes/team/mod.rs`
- [Product routes](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/routes/product/mod.rs): `backend/api/src/routes/product/mod.rs`
- [List routes](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/routes/list/mod.rs): `backend/api/src/routes/list/mod.rs`
- [Category routes](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/routes/category/mod.rs): `backend/api/src/routes/category/mod.rs`

### Authentication

- [Auth RPC contract](https://github.com/jkutkut/shoplist/blob/main/proto/auth.proto): `proto/auth.proto`
- [Auth service startup](https://github.com/jkutkut/shoplist/blob/main/backend/auth/src/main.rs): `backend/auth/src/main.rs`
- [Auth database adapter](https://github.com/jkutkut/shoplist/blob/main/backend/auth/src/db.rs): `backend/auth/src/db.rs`

### Persistence

- **PostgreSQL**
- [API database adapter](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/db/mod.rs): `backend/api/src/db/mod.rs`
- [API cache](https://github.com/jkutkut/shoplist/blob/main/backend/api/src/cache/mod.rs): `backend/api/src/cache/mod.rs`

### Other components

- **Shopper**
- **Account user**

## Connections

- Shopper → Product manager: manages products
- Shopper → List interface: manages lists
- Shopper → Team administration: administers team
- Product manager → Product service: creates updates deletes
- Team administration → Team service: requests membership
- User service → HTTP client: sends requests
- Team service → HTTP client: sends requests
- Product service → HTTP client: sends requests
- HTTP client → Fetch transport: dispatches HTTP
- Fetch transport → API startup: HTTP requests
- API startup → API database adapter: connects database
- API startup → API cache: initializes cache
- API startup → Route assembly: mounts routes
- Route assembly → User routes: assembles routes
- Route assembly → Team routes: assembles routes
- Route assembly → Product routes: assembles routes
- Route assembly → List routes: assembles routes
- Route assembly → Category routes: assembles routes
- Auth service startup → Auth database adapter: constructs adapter
- Auth service startup → Auth RPC contract: serves contract
- Auth service startup → PostgreSQL: connects database
- Account user → User service: account requests
- List interface → List context: reads list state