mnatakanijiiteajesasa/price-poa
Domain:
socioeconomicRecord type:
software
Creator:
mna
Host:
WhatsApp-native price intelligence agent for Kenya
# PricePoa — Development & Operations Guide
**WhatsApp and Telegram-native price intelligence agent for Kenya (under development)**
Kenya's location-aware grocery price comparison tool. This repository contains the scraper engine, backend API, Telegram bot endpoint, and database pipelines to crawl, normalize, and compare supermarket prices.
---
## 1. Project Architecture
The system is split into six primary microservices managed via Docker Compose:
| Service | Container Name | Technology | Internal Port | External Port | Purpose |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **mongo** | `pricepoa_mongo` | MongoDB 6.0 | `27017` | `27017` | Document database for products, prices, and scrape targets. |
| **mongo-express** | `pricepoa_mongo_express` | Node.js / Admin UI | `8081` | `8081` | Visual web interface for database management (Dev only). |
| **api** | `pricepoa_api` | FastAPI (Python 3.12) | `8000` | `8000` | Webhook endpoints for Telegram/WhatsApp and core API. |
| **scraper** | `pricepoa_scraper` | Scrapy / Playwright | - | - | Scheduled crawler and background worker. |
| **intelligence** | `pricepoa_intelligence` | Python 3.12 | - | - | NLP and machine learning services for product matching, recommendations, and analytics. |
| **qdrant** | `pricepoa_qdrant` | Qdrant Vector Database | `6333` | `6333` | Vector database for storing and searching product embeddings for semantic search. |
---
## 2. Quick Start: Spinning Up the Containers
Follow these steps to initialize and start the environment.
### Prerequisites
Ensure you have Docker and Docker Compose installed:
```bash
docker --version
docker compose version
```
### Step 1: Configure Environment Variables
Copy the template `.env.example` file and customize the variables if needed:
```bash
cp .env.example .env
```
### Step 2: Build & Start Core Services
Build the API and Scraper images (including downloading Playwright stealth web binaries), and start the database, backend, intelligence, and ve …