How 001ak/techfest-hackai-final works
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 Web App · shopping_assistant.py Shopping Assistant · store_api.py Store API · user_agent.py User Agent
Components 12
Web UI
Browser-facing request/response path for human users
- Browser User · Human shopper using the web interface
- Web App · Server-rendered application entrypoint
app.py - Search Page · Main input page for product queries
templates/index.html - Results Page · Shows matches, comparisons, and outcomes
templates/results.html - Unavailable Page · Fallback view for missing or unavailable products
templates/not_available.html - Stylesheet · Presentation styling for the server-rendered UI
static/style.css
Agent Core
uAgent-based shopping workflow and domain logic
- User Agent · Per-user agent runner that forwards shopping tasks
user_agent.py - Shopping Assistant · Central shopping backend agent on port 8000
shopping_assistant.py - Store API · Encapsulates search, availability, comparison, and purchase logic
store_api.py
Data Layer
Local sample catalog and supporting state
Other components
- Project Config · Dependencies and packaging setup
pyproject.toml
Connections 15
- 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