# 001ak/techfest-hackai-final architecture

> Architecture diagram of the GitHub repository 001ak/techfest-hackai-final, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/001ak/techfest-hackai-final
- Repository: https://github.com/001ak/techfest-hackai-final

## Overview

1. This repo is split into two main execution paths: a browser-facing web UI and a uAgent-based agent workflow. The agent side is the core of the product; the UI side provides the human entry point.

2. `shopping_assistant.py` is the central service. According to the README, it runs on port 8000 and acts as the shopping backend agent that answers search, comparison, availability, and purchase requests.

3. `user_agent.py` is the client-side agent runner. It runs on a separate port per user, uses the port number as a seed/identity, and sends shopping tasks to the shopping assistant after a delay or on demand. This is the main inter-agent boundary.

4. The data/model layer is intentionally simple and file-backed. `products.py` holds the sample product catalog used for searches and comparisons, while `data.json` likely stores supporting state or sample records. The README explicitly notes that this temporary product list can be replaced by a real database later.

5. `store_api.py` appears to encapsulate the store-domain operations: looking up products, checking availability, comparing prices, and handling purchase logic. Architecturally, it sits between agent requests and the product data source.

6. `app.py` is the web application entrypoint. The presence of `templates/` and `static/` strongly suggests a server-rendered interface for user input and result pages, rather than a purely API-only service.

7. The presentation layer is minimal and template-driven:
   - `templates/index.html` for the main search/input page
   - `templates/results.html` for displaying matches and comparisons
   - `templates/not_available.html` for out-of-stock or failed lookup cases
   - `static/style.css` for styling
   This indicates a server-rendered request/response flow rather than a SPA.

8. The typical request flow is: user submits a product query through the web UI or user agent, the request is resolved against the store/domain layer, the catalog is searched, and a result page or agent response is returned. Purchase checks add an availability gate before confirming the transaction.

9. The system boundary is mostly local and process-based, not cloud-native: one Python process for the shopping assistant, another for each user agent, and a web process for the UI. There is no evidence of external infrastructure, queues, or a database service in the repo.

10. `pyproject.toml` defines the Python project and dependencies; the README calls out `uAgent` and `python-decouple`, so the implementation is Python-first and agent-oriented, with environment/config handling kept lightweight.

11. For an architecture diagram, the clearest boxes are:
   - User/browser UI
   - Web app controller (`app.py` + templates/static)
   - User agent process (`user_agent.py`)
   - Shopping assistant agent (`shopping_assistant.py`)
   - Store/domain logic (`store_api.py`)
   - Product catalog/data files (`products.py`, `data.json`)
   with arrows showing user requests flowing into the assistant and responses flowing back to the originating user agent/UI.

12. The main design constraint is that product state is local and temporary. The repo is structured so the catalog can be swapped out later, but today the business logic depends on in-repo sample data rather than an external system.

Main entry points: [`app.py`](https://github.com/001ak/techfest-hackai-final/blob/main/app.py) (Web App), [`shopping_assistant.py`](https://github.com/001ak/techfest-hackai-final/blob/main/shopping_assistant.py) (Shopping Assistant), [`store_api.py`](https://github.com/001ak/techfest-hackai-final/blob/main/store_api.py) (Store API), [`user_agent.py`](https://github.com/001ak/techfest-hackai-final/blob/main/user_agent.py) (User Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web_ui["Web UI"]
  node_browser_user(("Browser User<br/>actor"))
  node_app_entry["Web App<br/>web entrypoint<br/>[app.py]"]
  node_index_tpl["Search Page<br/>template<br/>[index.html]"]
  node_results_tpl["Results Page<br/>template<br/>[results.html]"]
  node_notavail_tpl["Unavailable Page<br/>template<br/>[not_available.html]"]
  node_styles["Stylesheet<br/>asset<br/>[style.css]"]
end

subgraph group_agent_core["Agent Core"]
  node_user_agent["User Agent<br/>agent client<br/>[user_agent.py]"]
  node_shopping_assistant["Shopping Assistant<br/>agent service"]
  node_store_api["Store API<br/>domain service<br/>[store_api.py]"]
end

subgraph group_data_layer["Data Layer"]
  node_product_catalog[("Catalog<br/>sample data<br/>[products.py]")]
  node_state_file["Data File<br/>local state<br/>[data.json]"]
end

node_config["Project Config<br/>python project<br/>[pyproject.toml]"]

node_browser_user -->|"submit query"| node_app_entry
node_app_entry -->|"render"| node_index_tpl
node_app_entry -->|"render"| node_results_tpl
node_app_entry -->|"render"| node_notavail_tpl
node_app_entry -->|"load assets"| node_styles
node_app_entry -->|"dispatch task"| node_user_agent
node_user_agent -->|"send request"| node_shopping_assistant
node_shopping_assistant -->|"invoke"| node_store_api
node_store_api -->|"read catalog"| node_product_catalog
node_store_api -->|"read state"| node_state_file
node_store_api -->|"return result"| node_shopping_assistant
node_shopping_assistant -->|"reply"| node_user_agent
node_user_agent -->|"deliver response"| node_browser_user
node_config -.->|"configure"| node_app_entry
node_config -.->|"configure"| node_shopping_assistant

click node_app_entry "https://github.com/001ak/techfest-hackai-final/blob/main/app.py"
click node_index_tpl "https://github.com/001ak/techfest-hackai-final/blob/main/templates/index.html"
click node_results_tpl "https://github.com/001ak/techfest-hackai-final/blob/main/templates/results.html"
click node_notavail_tpl "https://github.com/001ak/techfest-hackai-final/blob/main/templates/not_available.html"
click node_styles "https://github.com/001ak/techfest-hackai-final/blob/main/static/style.css"
click node_user_agent "https://github.com/001ak/techfest-hackai-final/blob/main/user_agent.py"
click node_shopping_assistant "https://github.com/001ak/techfest-hackai-final/blob/main/shopping_assistant.py"
click node_store_api "https://github.com/001ak/techfest-hackai-final/blob/main/store_api.py"
click node_product_catalog "https://github.com/001ak/techfest-hackai-final/blob/main/products.py"
click node_state_file "https://github.com/001ak/techfest-hackai-final/blob/main/data.json"
click node_config "https://github.com/001ak/techfest-hackai-final/blob/main/pyproject.toml"

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_browser_user,node_app_entry,node_index_tpl,node_results_tpl,node_notavail_tpl,node_styles toneBlue
class node_user_agent,node_shopping_assistant,node_store_api toneAmber
class node_product_catalog,node_state_file toneMint
class node_config toneNeutral
```

## Components

### Web UI

Browser-facing request/response path for human users

- **Browser User**: actor · Human shopper using the web interface
- [Web App](https://github.com/001ak/techfest-hackai-final/blob/main/app.py): web entrypoint · Server-rendered application entrypoint · `app.py`
- [Search Page](https://github.com/001ak/techfest-hackai-final/blob/main/templates/index.html): template · Main input page for product queries · `templates/index.html`
- [Results Page](https://github.com/001ak/techfest-hackai-final/blob/main/templates/results.html): template · Shows matches, comparisons, and outcomes · `templates/results.html`
- [Unavailable Page](https://github.com/001ak/techfest-hackai-final/blob/main/templates/not_available.html): template · Fallback view for missing or unavailable products · `templates/not_available.html`
- [Stylesheet](https://github.com/001ak/techfest-hackai-final/blob/main/static/style.css): asset · Presentation styling for the server-rendered UI · `static/style.css`

### Agent Core

uAgent-based shopping workflow and domain logic

- [User Agent](https://github.com/001ak/techfest-hackai-final/blob/main/user_agent.py): agent client · Per-user agent runner that forwards shopping tasks · `user_agent.py`
- [Shopping Assistant](https://github.com/001ak/techfest-hackai-final/blob/main/shopping_assistant.py): agent service · Central shopping backend agent on port 8000 · `shopping_assistant.py`
- [Store API](https://github.com/001ak/techfest-hackai-final/blob/main/store_api.py): domain service · Encapsulates search, availability, comparison, and purchase logic · `store_api.py`

### Data Layer

Local sample catalog and supporting state

- [Catalog](https://github.com/001ak/techfest-hackai-final/blob/main/products.py): sample data · Local product list used for lookup and comparison · `products.py`
- [Data File](https://github.com/001ak/techfest-hackai-final/blob/main/data.json): local state · File-backed supporting records or sample state · `data.json`

### Other components

- [Project Config](https://github.com/001ak/techfest-hackai-final/blob/main/pyproject.toml): python project · Dependencies and packaging setup · `pyproject.toml`

## Connections

- Browser User → Web App: submit query · User sends a product request through the web UI
- Web App → Search Page: render · Serves the main search/input page
- Web App → Results Page: render · Displays matched products and comparisons
- Web App → Unavailable Page: render · Displays unavailable or failed lookup state
- Web App → Stylesheet: load assets · Uses stylesheet for the rendered pages
- Web App → User Agent: dispatch task · Forwards user-intent shopping requests to the agent runner
- User Agent → Shopping Assistant: send request · Client agent submits shopping work after a delay or on demand
- Shopping Assistant → Store API: invoke · Routes search, comparison, availability, and purchase operations
- Store API → Catalog: read catalog · Looks up products from the local sample list
- Store API → Data File: read state · Uses file-backed supporting records when needed
- Store API → Shopping Assistant: return result · Returns domain outcome to the assistant
- Shopping Assistant → User Agent: reply · Returns the shopping response to the originating agent
- User Agent → Browser User: deliver response · Presents the outcome back to the user flow
- Project Config → Web App: configure · Defines project/runtime dependencies for the web process
- Project Config → Shopping Assistant: configure · Defines project/runtime dependencies for the agent process
