# hf-cygg/y-link architecture

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

- Interactive diagram: https://gitdiagram.com/hf-cygg/y-link
- Repository: https://github.com/hf-cygg/y-link

## Overview

Y-Link is an inventory and O2O reservation system for cultural-product stores and events. Its main user workflow spans catalog discovery, reservation/order placement, offline verification, inbound and outbound stock operations, inventory tracking, and customer feedback; administrators and operators also manage products, users, settings, and audit records. The Vue client and admin front ends use an Express/TypeORM backend with SQLite by default and optional MySQL migration. Mobile is an Expo foundation, not a live client: the README says real API, session, cart, order, inventory, returns, and device integrations are not yet connected. Links are limited to README statements and shown source-index references.

Main entry points: [`src/api/http.ts`](https://github.com/hf-cygg/y-link/blob/main/src/api/http.ts) (HTTP request layer), [`src/views/client`](https://github.com/hf-cygg/y-link/tree/main/src/views/client) (Client web), [`src/App.vue`](https://github.com/hf-cygg/y-link/blob/main/src/App.vue) (Admin web), [`backend/src/app.ts`](https://github.com/hf-cygg/y-link/blob/main/backend/src/app.ts) (Express API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experiences"]
  node_clientweb["Client web"]
  node_clientauth["Client authentication<br/>[ClientAuthView.vue]"]
  node_mall["Product mall<br/>[o2o.ts]"]
  node_cart["Cart and checkout<br/>[client-cart.ts]"]
  node_clientorders["Orders and returns<br/>[client-order.ts]"]
  node_feedback["Customer feedback"]
  node_adminweb["Admin web<br/>[App.vue]"]
  node_catalogadmin["Product management<br/>[ProductManager.vue]"]
  node_operations["Stock operations<br/>[inventory.ts]"]
  node_adminorders["Order operations<br/>[order.ts]"]
  node_governance["Users, settings, audit<br/>[system-config.ts]"]
  node_http["HTTP request layer<br/>[http.ts]"]
end

subgraph group_backend["Backend services"]
  node_api["Express API<br/>[app.ts]"]
  node_clientauthsvc["Client auth service"]
  node_reservation["O2O reservation service"]
  node_inventorysvc["Inventory queries"]
end

subgraph group_data["Persistence and contracts"]
  node_database[("Business database")]
  node_apiclient["Shared API client<br/>[client-auth.ts]"]
  node_sharedtypes["Shared contracts"]
end

subgraph group_mobile["Mobile foundation"]
  node_mobile["Expo mobile app"]
  node_mobileproviders["Mobile providers<br/>[AppProviders.tsx]"]
  node_mobilecontracts["Mobile shared contracts<br/>[shared-packages.ts]"]
end

node_customers(("Customers"))
node_staff(("Admin and operators"))

node_customers -->|"use"| node_clientweb
node_staff -->|"manage through"| node_adminweb
node_clientweb -->|"register and sign in"| node_clientauth
node_clientauth -->|"requests"| node_http
node_http -->|"sends API requests"| node_api
node_api -->|"handles client auth"| node_clientauthsvc
node_clientweb -->|"browse catalog"| node_mall
node_mall -->|"uses"| node_http
node_clientweb -->|"build cart"| node_cart
node_clientweb -->|"place and track orders"| node_clientorders
node_clientweb -->|"send feedback"| node_feedback
node_adminweb -->|"maintain products"| node_catalogadmin
node_adminweb -->|"manage stock"| node_operations
node_adminweb -->|"manage orders"| node_adminorders
node_adminweb -->|"manage users and audit"| node_governance
node_catalogadmin -->|"uses"| node_http
node_operations -->|"uses"| node_http
node_adminorders -->|"uses"| node_http
node_governance -->|"uses"| node_http
node_api -->|"routes O2O requests"| node_reservation
node_api -.->|"serves inventory queries"| node_inventorysvc
node_reservation -.->|"persists reservations"| node_database
node_inventorysvc -->|"reads stock records"| node_database
node_api -->|"stores business data"| node_database
node_apiclient -->|"uses contracts"| node_sharedtypes
node_mobile -.->|"initializes providers"| node_mobileproviders
node_mobile -->|"declares package boundary"| node_mobilecontracts
node_mobile -.->|"not yet integrated"| node_apiclient

click node_clientweb "https://github.com/hf-cygg/y-link/tree/main/src/views/client"
click node_clientauth "https://github.com/hf-cygg/y-link/blob/main/src/views/client/ClientAuthView.vue"
click node_mall "https://github.com/hf-cygg/y-link/blob/main/src/api/modules/o2o.ts"
click node_cart "https://github.com/hf-cygg/y-link/blob/main/src/store/modules/client-cart.ts"
click node_clientorders "https://github.com/hf-cygg/y-link/blob/main/src/store/modules/client-order.ts"
click node_feedback "https://github.com/hf-cygg/y-link/blob/main/src/api/modules/customer-service-feedback.ts"
click node_adminweb "https://github.com/hf-cygg/y-link/blob/main/src/App.vue"
click node_catalogadmin "https://github.com/hf-cygg/y-link/blob/main/src/views/base-data/components/ProductManager.vue"
click node_operations "https://github.com/hf-cygg/y-link/blob/main/src/api/modules/inventory.ts"
click node_adminorders "https://github.com/hf-cygg/y-link/blob/main/src/api/modules/order.ts"
click node_governance "https://github.com/hf-cygg/y-link/blob/main/src/api/modules/system-config.ts"
click node_http "https://github.com/hf-cygg/y-link/blob/main/src/api/http.ts"
click node_api "https://github.com/hf-cygg/y-link/blob/main/backend/src/app.ts"
click node_clientauthsvc "https://github.com/hf-cygg/y-link/blob/main/backend/src/services/client-auth.service.ts"
click node_reservation "https://github.com/hf-cygg/y-link/blob/main/backend/src/services/o2o-preorder.service.ts"
click node_inventorysvc "https://github.com/hf-cygg/y-link/blob/main/backend/src/services/inventory-query.service.ts"
click node_database "https://github.com/hf-cygg/y-link/tree/main/backend/src/entities"
click node_apiclient "https://github.com/hf-cygg/y-link/blob/main/packages/api-client/src/modules/client-auth.ts"
click node_sharedtypes "https://github.com/hf-cygg/y-link/tree/main/packages/shared-types/src"
click node_mobile "https://github.com/hf-cygg/y-link/tree/main/apps/mobile/app"
click node_mobileproviders "https://github.com/hf-cygg/y-link/blob/main/apps/mobile/src/app/providers/AppProviders.tsx"
click node_mobilecontracts "https://github.com/hf-cygg/y-link/blob/main/apps/mobile/src/contracts/shared-packages.ts"

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_clientweb,node_clientauth,node_mall,node_cart,node_clientorders,node_feedback,node_adminweb,node_catalogadmin,node_operations,node_adminorders,node_governance,node_http toneBlue
class node_api,node_clientauthsvc,node_reservation,node_inventorysvc toneAmber
class node_database,node_apiclient,node_sharedtypes toneMint
class node_mobile,node_mobileproviders,node_mobilecontracts toneRose
class node_customers,node_staff toneIndigo
```

## Components

### Web experiences

- [Client web](https://github.com/hf-cygg/y-link/tree/main/src/views/client): `src/views/client`
- [Client authentication](https://github.com/hf-cygg/y-link/blob/main/src/views/client/ClientAuthView.vue): `src/views/client/ClientAuthView.vue`
- [Product mall](https://github.com/hf-cygg/y-link/blob/main/src/api/modules/o2o.ts): `src/api/modules/o2o.ts`
- [Cart and checkout](https://github.com/hf-cygg/y-link/blob/main/src/store/modules/client-cart.ts): `src/store/modules/client-cart.ts`
- [Orders and returns](https://github.com/hf-cygg/y-link/blob/main/src/store/modules/client-order.ts): `src/store/modules/client-order.ts`
- [Customer feedback](https://github.com/hf-cygg/y-link/blob/main/src/api/modules/customer-service-feedback.ts): `src/api/modules/customer-service-feedback.ts`
- [Admin web](https://github.com/hf-cygg/y-link/blob/main/src/App.vue): `src/App.vue`
- [Product management](https://github.com/hf-cygg/y-link/blob/main/src/views/base-data/components/ProductManager.vue): `src/views/base-data/components/ProductManager.vue`
- [Stock operations](https://github.com/hf-cygg/y-link/blob/main/src/api/modules/inventory.ts): `src/api/modules/inventory.ts`
- [Order operations](https://github.com/hf-cygg/y-link/blob/main/src/api/modules/order.ts): `src/api/modules/order.ts`
- [Users, settings, audit](https://github.com/hf-cygg/y-link/blob/main/src/api/modules/system-config.ts): `src/api/modules/system-config.ts`
- [HTTP request layer](https://github.com/hf-cygg/y-link/blob/main/src/api/http.ts): `src/api/http.ts`

### Backend services

- [Express API](https://github.com/hf-cygg/y-link/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Client auth service](https://github.com/hf-cygg/y-link/blob/main/backend/src/services/client-auth.service.ts): `backend/src/services/client-auth.service.ts`
- [O2O reservation service](https://github.com/hf-cygg/y-link/blob/main/backend/src/services/o2o-preorder.service.ts): `backend/src/services/o2o-preorder.service.ts`
- [Inventory queries](https://github.com/hf-cygg/y-link/blob/main/backend/src/services/inventory-query.service.ts): `backend/src/services/inventory-query.service.ts`

### Persistence and contracts

- [Business database](https://github.com/hf-cygg/y-link/tree/main/backend/src/entities): `backend/src/entities`
- [Shared API client](https://github.com/hf-cygg/y-link/blob/main/packages/api-client/src/modules/client-auth.ts): `packages/api-client/src/modules/client-auth.ts`
- [Shared contracts](https://github.com/hf-cygg/y-link/tree/main/packages/shared-types/src): `packages/shared-types/src`

### Mobile foundation

- [Expo mobile app](https://github.com/hf-cygg/y-link/tree/main/apps/mobile/app): `apps/mobile/app`
- [Mobile providers](https://github.com/hf-cygg/y-link/blob/main/apps/mobile/src/app/providers/AppProviders.tsx): `apps/mobile/src/app/providers/AppProviders.tsx`
- [Mobile shared contracts](https://github.com/hf-cygg/y-link/blob/main/apps/mobile/src/contracts/shared-packages.ts): `apps/mobile/src/contracts/shared-packages.ts`

### Other components

- **Customers**
- **Admin and operators**

## Connections

- Customers → Client web: use (evidence: `README.md`)
- Admin and operators → Admin web: manage through (evidence: `README.md`)
- Client web → Client authentication: register and sign in (evidence: `README.md`)
- Client authentication → HTTP request layer: requests (evidence: `src/views/client/ClientAuthView.vue`)
- HTTP request layer → Express API: sends API requests (evidence: `README.md`)
- Express API → Client auth service: handles client auth
- Client web → Product mall: browse catalog (evidence: `README.md`)
- Product mall → HTTP request layer: uses (evidence: `src/api/modules/o2o.ts`)
- Client web → Cart and checkout: build cart (evidence: `README.md`)
- Client web → Orders and returns: place and track orders (evidence: `README.md`)
- Client web → Customer feedback: send feedback (evidence: `README.md`)
- Admin web → Product management: maintain products (evidence: `README.md`)
- Admin web → Stock operations: manage stock (evidence: `README.md`)
- Admin web → Order operations: manage orders (evidence: `README.md`)
- Admin web → Users, settings, audit: manage users and audit (evidence: `README.md`)
- Product management → HTTP request layer: uses (evidence: `src/views/base-data/components/ProductManager.vue`)
- Stock operations → HTTP request layer: uses (evidence: `README.md`)
- Order operations → HTTP request layer: uses (evidence: `README.md`)
- Users, settings, audit → HTTP request layer: uses (evidence: `README.md`)
- Express API → O2O reservation service: routes O2O requests
- Express API → Inventory queries: serves inventory queries
- O2O reservation service → Business database: persists reservations
- Inventory queries → Business database: reads stock records (evidence: `backend/src/services/inventory-query.service.ts`)
- Express API → Business database: stores business data (evidence: `README.md`)
- Shared API client → Shared contracts: uses contracts (evidence: `packages/api-client/src/modules/client-auth.ts`)
- Expo mobile app → Mobile providers: initializes providers
- Expo mobile app → Mobile shared contracts: declares package boundary (evidence: `README.md`)
- Expo mobile app → Shared API client: not yet integrated (evidence: `README.md`)
