# xitenglongping755-cell/group21-step3-1 architecture

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

- Interactive diagram: https://gitdiagram.com/xitenglongping755-cell/group21-step3-1
- Repository: https://github.com/xitenglongping755-cell/group21-step3-1

## Overview

Giftia is a gift-discovery application: users search products by keyword, category, packaging and price, or use a family-birthday flow with tags and optional relation. The frontend loads tag choices, submits the active tab’s conditions to FastAPI, and renders ranked results as cards. The API queries the product database and adapts rows to the frontend’s Gift shape. The family UI supports featured cards, reasons and gift-giver voices, although the sampled backend does not show those fields being populated. Relationships reflect the excerpts and documented contracts; unsampled implementations are not inferred.

Main entry points: [`giftia-fromtend/lib/api.ts`](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/giftia-fromtend/lib/api.ts) (API client), [`giftia-fromtend/app/page.tsx`](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/giftia-fromtend/app/page.tsx) (Search page), [`backend/database.py`](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/database.py) (Query helper), [`backend/main.py`](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/main.py) (Standard search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Giftia frontend"]
  node_home["Search page<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_result_card["Result card<br/>[ResultCard.tsx]"]
end

subgraph group_api["Search API"]
  node_standard_search["Standard search<br/>[main.py]"]
  node_family_search["Family search<br/>[main.py]"]
  node_tag_options["Usage tags<br/>[main.py]"]
  node_gift_mapping["Gift mapping<br/>[main.py]"]
end

subgraph group_data["Product data"]
  node_query_helper["Query helper<br/>[database.py]"]
  node_gift_database[("Gift database")]
end

node_visitor(("Gift seeker"))

node_visitor -->|"uses"| node_home
node_home -->|"requests search"| node_api_client
node_home -->|"loads tags"| node_api_client
node_home -->|"renders results"| node_result_card
node_api_client -->|"calls /api/search"| node_standard_search
node_api_client -->|"calls /api/family-search"| node_family_search
node_api_client -->|"calls /api/usage-tags"| node_tag_options
node_standard_search -->|"queries products"| node_query_helper
node_family_search -->|"queries products and tags"| node_query_helper
node_tag_options -->|"reads tag choices"| node_query_helper
node_standard_search -->|"maps result rows"| node_gift_mapping
node_family_search -->|"maps result rows"| node_gift_mapping
node_query_helper -->|"executes SELECT"| node_gift_database

click node_home "https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/giftia-fromtend/app/page.tsx"
click node_api_client "https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/giftia-fromtend/lib/api.ts"
click node_result_card "https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/giftia-fromtend/app/ResultCard.tsx"
click node_standard_search "https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/main.py"
click node_family_search "https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/main.py"
click node_tag_options "https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/main.py"
click node_gift_mapping "https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/main.py"
click node_query_helper "https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/database.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_home,node_api_client,node_result_card toneBlue
class node_standard_search,node_family_search,node_tag_options,node_gift_mapping toneAmber
class node_query_helper,node_gift_database toneMint
class node_visitor toneIndigo
```

## Components

### Giftia frontend

- [Search page](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/giftia-fromtend/app/page.tsx): `giftia-fromtend/app/page.tsx`
- [API client](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/giftia-fromtend/lib/api.ts): `giftia-fromtend/lib/api.ts`
- [Result card](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/giftia-fromtend/app/ResultCard.tsx): `giftia-fromtend/app/ResultCard.tsx`

### Search API

- [Standard search](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/main.py): `backend/main.py`
- [Family search](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/main.py): `backend/main.py`
- [Usage tags](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/main.py): `backend/main.py`
- [Gift mapping](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/main.py): `backend/main.py`

### Product data

- [Query helper](https://github.com/xitenglongping755-cell/group21-step3-1/blob/main/backend/database.py): `backend/database.py`
- **Gift database**

### Other components

- **Gift seeker**

## Connections

- Gift seeker → Search page: uses (evidence: `giftia-fromtend/app/page.tsx`)
- Search page → API client: requests search (evidence: `giftia-fromtend/app/page.tsx`)
- Search page → API client: loads tags (evidence: `giftia-fromtend/app/page.tsx`)
- Search page → Result card: renders results (evidence: `giftia-fromtend/app/page.tsx`)
- API client → Standard search: calls /api/search (evidence: `giftia-fromtend/lib/api.ts`)
- API client → Family search: calls /api/family-search (evidence: `giftia-fromtend/lib/api.ts`)
- API client → Usage tags: calls /api/usage-tags (evidence: `giftia-fromtend/lib/api.ts`)
- Standard search → Query helper: queries products (evidence: `backend/main.py`)
- Family search → Query helper: queries products and tags (evidence: `backend/main.py`)
- Usage tags → Query helper: reads tag choices (evidence: `backend/main.py`)
- Standard search → Gift mapping: maps result rows (evidence: `backend/main.py`)
- Family search → Gift mapping: maps result rows (evidence: `backend/main.py`)
- Query helper → Gift database: executes SELECT (evidence: `backend/database.py`)
