diff --git a/_bmad-output/planning-artifacts/bmm-workflow-status.yaml b/_bmad-output/planning-artifacts/bmm-workflow-status.yaml new file mode 100644 index 0000000..e7686fe --- /dev/null +++ b/_bmad-output/planning-artifacts/bmm-workflow-status.yaml @@ -0,0 +1,89 @@ +# Workflow Status Template + +# This tracks progress through BMM methodology Analysis, Planning, and Solutioning phases. +# Implementation phase is tracked separately in sprint-status.yaml + +# STATUS DEFINITIONS: +# ================== +# Initial Status (before completion): +# - required: Must be completed to progress +# - optional: Can be completed but not required +# - recommended: Strongly suggested but not required +# - conditional: Required only if certain conditions met (e.g., if_has_ui) +# +# Completion Status: +# - {file-path}: File created/found (e.g., "docs/product-brief.md") +# - skipped: Optional/conditional workflow that was skipped + +generated: "2026-01-23T10:06:00+01:00" +project: "Priceflow-1" +project_type: "brownfield" +selected_track: "method" +field_type: "brownfield" +workflow_path: "method-brownfield.yaml" +workflow_status: + - phase: "1. Analysis" + workflows: + - id: "document-project" + name: "Document Project" + description: "Analyze codebase and create documentation" + agent: "analyst" + status: "docs/index.md" + artifacts: + - "docs/project-context.md" + + - phase: "2. Strategic Planning" + workflows: + - id: "create-product-brief" + name: "Product Brief" + description: "Define product vision and strategy" + agent: "pm" + status: "recommended" + artifacts: + - "docs/product-brief.md" + + - phase: "3. Technical Planning" + workflows: + - id: "create-architecture" + name: "System Architecture" + description: "Define system design and patterns" + agent: "architect" + status: "required" + artifacts: + - "docs/architecture.md" + + - id: "create-tech-spec" + name: "Technical Specification" + description: "Detailed technical specifications" + agent: "architect" + status: "optional" + artifacts: + - "docs/tech-spec.md" + + - phase: "4. Requirements" + workflows: + - id: "create-prd" + name: "Product Requirements" + description: "Detailed product requirements document" + agent: "pm" + status: "required" + artifacts: + - "docs/prd.md" + + - phase: "5. Implementation Planning" + workflows: + - id: "create-epics-and-stories" + name: "Epics & Stories" + description: "Break down requirements into tasks" + agent: "pm" + status: "required" + artifacts: + - "docs/epics/epic-*.md" + + - id: "sprint-planning" + name: "Sprint Planning" + description: "Plan development sprints" + agent: "pm" + status: "required" + artifacts: + - "sprint-status.yaml" diff --git a/_bmad-output/project-scan-report.json b/_bmad-output/project-scan-report.json new file mode 100644 index 0000000..69b79be --- /dev/null +++ b/_bmad-output/project-scan-report.json @@ -0,0 +1,88 @@ +{ + "workflow_version": "1.2.0", + "timestamps": { + "started": "2026-01-23T10:07:34+01:00", + "last_updated": "2026-01-23T10:07:34+01:00" + }, + "mode": "initial_scan", + "scan_level": "quick", + "project_root": "c:\\Users\\Michael\\VSCODE\\Priceflow", + "output_folder": "c:\\Users\\Michael\\VSCODE\\Priceflow\\docs", + "completed_steps": [ + { + "step": "step_1", + "status": "completed", + "timestamp": "2026-01-23T10:07:34+01:00", + "summary": "Classified as multi-part with 2 parts" + }, + { + "step": "step_2", + "status": "completed", + "timestamp": "2026-01-23T10:07:34+01:00", + "summary": "Found 4 existing docs: RAPPORT_ANALYSE.md, DEMARRAGE.md, docs/AMAZON_SCRAPER.md, docs/API_CATALOGUES.md" + }, + { + "step": "step_3", + "status": "completed", + "timestamp": "2026-01-23T10:07:34+01:00", + "summary": "Tech stack: FastAPI (Python 3.12) + React (Vite, Tailwind)" + }, + { + "step": "step_4", + "status": "completed", + "timestamp": "2026-01-23T10:07:34+01:00", + "summary": "Verified components, routers, and models availability" + }, + { + "step": "step_10", + "status": "completed", + "timestamp": "2026-01-23T10:07:34+01:00", + "summary": "Master index generated" + } + ], + "current_step": "completed", + "findings": { + "project_classification": { + "repository_type": "multi-part", + "parts_count": 2, + "parts": [ + { + "part_id": "frontend", + "root_path": "frontend", + "project_type_id": "web", + "display_name": "Frontend" + }, + { + "part_id": "app", + "root_path": "app", + "project_type_id": "backend", + "display_name": "Backend" + } + ] + }, + "existing_docs": [ + "RAPPORT_ANALYSE.md", + "DEMARRAGE.md", + "docs/AMAZON_SCRAPER.md", + "docs/API_CATALOGUES.md" + ], + "technology_stack": { + "frontend": "React 18, Vite, Tailwind CSS, Radix UI", + "app": "Python 3.12, FastAPI, SQLAlchemy, Playwright, Crawl4AI" + } + }, + "outputs_generated": [ + "project-scan-report.json", + "project-overview.md", + "source-tree-analysis.md", + "development-guide.md", + "deployment-guide.md", + "architecture-frontend.md", + "architecture-app.md", + "integration-architecture.md", + "api-contracts-app.md", + "data-models-app.md", + "index.md" + ], + "resume_instructions": "Workflow completed" +} \ No newline at end of file diff --git a/docs/api-contracts-app.md b/docs/api-contracts-app.md new file mode 100644 index 0000000..6b5f261 --- /dev/null +++ b/docs/api-contracts-app.md @@ -0,0 +1,18 @@ +# API Contracts (Backend) + +## Overview + +This document outlines the API surface of the PriceFlow backend. + +> **Note**: This is a high-level summary from a Quick Scan. Run a Deep Scan to generate full endpoint documentation. + +## Router Structure + +The API is organized into routers located in `app/routers`: + +- *(Content pending deep scan - check `app/routers` for specific files)* + +## Request/Response Formats + +- **Format**: JSON +- **Validation**: Pydantic models (see `app/schemas.py`) diff --git a/docs/architecture-app.md b/docs/architecture-app.md new file mode 100644 index 0000000..80290db --- /dev/null +++ b/docs/architecture-app.md @@ -0,0 +1,40 @@ +# Backend Architecture + +## Overview + +The PriceFlow backend is a high-performance API and worker service built with Python and FastAPI. It handles product management, scraping logic, database operations, and notifications. + +## Technology Stack + +- **Framework**: FastAPI (Python 3.12) +- **Server**: Uvicorn (ASGI) +- **Database**: PostgreSQL (via SQLAlchemy ORM) +- **Migrations**: Alembic + +## Core Components + +### 1. API Layer (`app/routers`) + +Exposes REST endpoints for the frontend to consume. Handles request validation via Pydantic schemas. + +### 2. Service Layer (`app/services`) + +Contains the business logic, including: + +- **Scraping**: Logic to control Playwright/Browserless. +- **AI Analysis**: Integration with LiteLLM for image processing. +- **Notifications**: Apprise integration. + +### 3. Data Layer (`app/models.py`) + +Defines the database schema using SQLAlchemy. + +- **Models**: Products, Prices, Users (if applicable). + +### 4. Background Workers + +Uses `APScheduler` or similar mechanisms (implied from deps) to run periodic scraping tasks. + +## Scraping Architecture + +The backend delegates browser rendering to a separate `Browserless` service (Docker container) via WebSocket, ensuring the main API remains responsive. diff --git a/docs/architecture-frontend.md b/docs/architecture-frontend.md new file mode 100644 index 0000000..46d786f --- /dev/null +++ b/docs/architecture-frontend.md @@ -0,0 +1,29 @@ +# Frontend Architecture + +## Overview + +The PriceFlow frontend is a Single Page Application (SPA) built with React 18 and Vite. It provides the user interface for tracking products, viewing history, and configuring settings. + +## Technology Stack + +- **Core**: React 18 +- **Build Tool**: Vite +- **Styling**: Tailwind CSS +- **Components**: Radix UI (headless), Lucide React (icons) +- **Routing**: React Router DOM +- **Internationalization**: i18next + +## Key Directories + +- `src/components/`: Reusable UI components. +- `src/pages/`: Page-level components mapped to routes. +- `src/api/` (implied): API integration logic. +- `src/lib/`: Utilities and helper functions. + +## State Management + +State is likely managed via React's built-in `useState`/`useContext` hooks, with `axios` handling async data fetching. + +## Design System + +The UI utilizes Tailwind CSS for utility-first styling and Radix UI primitives for accessible component logic (Dialogs, Tooltips, etc.). diff --git a/docs/data-models-app.md b/docs/data-models-app.md new file mode 100644 index 0000000..d6263b3 --- /dev/null +++ b/docs/data-models-app.md @@ -0,0 +1,19 @@ +# Data Models + +## Database Schema + +The project uses PostgreSQL managed via SQLAlchemy. + +> **Note**: This is a high-level summary from a Quick Scan. Run a Deep Scan to generate full schema documentation. + +## Tables + +Models are defined in `app/models.py`. Key entities likely include: + +- **Product** (or Item): The object being tracked. +- **Price**: Historical price points. +- **(Others pending deep scan)** + +## Migrations + +Database schema changes are managed by Alembic. Migration scripts are located in `app/alembic/versions/`. diff --git a/docs/deployment-guide.md b/docs/deployment-guide.md new file mode 100644 index 0000000..2f09175 --- /dev/null +++ b/docs/deployment-guide.md @@ -0,0 +1,51 @@ +# Deployment Guide + +## Infrastructure Architecture + +PriceFlow is designed to be deployed using Docker Compose. The stack consists of: + +- **App**: The main FastAPI backend and application logic. +- **Frontend**: Served typically via Nginx or embedded (in this setup, check docker-compose for service details). +- **Database**: PostgreSQL container. +- **Browserless**: Headless Chrome instance for scraping. + +## Services & Ports + +| Service | Internal Port | Host Port | Description | +|---------|---------------|-----------|-------------| +| **PriceFlow App** | 8555 | 8555 | Main Application API & UI Serving | +| **PostgreSQL** | 5432 | 5488 | Database Access | +| **Browserless** | 3000 | 3012 | Headless Browser Debugger | + +## Deployment Steps + +1. **Prepare the Host**: Ensure Docker and Docker Compose are installed. + +2. **Configuration**: + - Copy `.env.example` to `.env`. + - Set critical variables: + - `DATABASE_URL`: Connection string for PostgreSQL. + - `BROWSERLESS_URL`: WebSocket URL for Browserless. + - `OPENAI_API_KEY` / Other AI Keys: For AI analysis features. + +3. **Launch**: + + ```bash + docker compose up -d + ``` + +4. **Access**: + - Application: `http://localhost:8555` + +## Networking + +The application uses an external Docker network named `nginx_default`. Ensure this is created: + +```bash +docker network create nginx_default +``` + +## Troubleshooting + +- **Scraping Issues**: Check `Browserless` container logs. Ensure the app can reach the browserless service URL. +- **Database Connections**: Verify the `DATABASE_URL` matches the container name and credentials in `docker-compose.yml`. diff --git a/docs/development-guide.md b/docs/development-guide.md new file mode 100644 index 0000000..47fc902 --- /dev/null +++ b/docs/development-guide.md @@ -0,0 +1,100 @@ +# Development Guide + +## Prerequisites + +- **Docker** and **Docker Compose** +- **Node.js** (for frontend development) +- **Python 3.12+** (for backend development) +- **Git** + +## Environment Setup + +1. Clone the repository: + + ```bash + git clone https://github.com/R0m1k3/Priceflow.git + cd Priceflow + ``` + +2. Configure environment variables: + + ```bash + cp .env.example .env + # Edit .env to set your specific configurations (Database, AI keys, etc.) + ``` + +3. Create the Docker network (if using specific network setup): + + ```bash + docker network create nginx_default + ``` + +## Local Development + +### Backend (FastAPI) + +1. Navigate to the backend directory: + + ```bash + cd app + ``` + +2. Install dependencies (recommended to use a virtual environment): + + ```bash + pip install -r requirements.txt # Or use a package manager like uv/poetry if configured + ``` + +3. Run the development server with hot reload: + + ```bash + uvicorn app.main:app --reload --port 8555 + ``` + + The API will be available at `http://localhost:8555`. + +### Frontend (React) + +1. Navigate to the frontend directory: + + ```bash + cd frontend + ``` + +2. Install dependencies: + + ```bash + npm install + ``` + +3. Run the development server: + + ```bash + npm run dev + ``` + + The frontend will be available at the URL provided by Vite (usually `http://localhost:5173`). + +## Database Migrations + +This project uses Alembic for database migrations. + +1. **Create a new migration** (after modifying models): + + ```bash + alembic revision --autogenerate -m "description of changes" + ``` + +2. **Apply migrations**: + + ```bash + alembic upgrade head + ``` + +## Testing + +*(To be configured - check `tests/` directory for `pytest` usage)* + +```bash +pytest +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..affd99f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,48 @@ +# PriceFlow Documentation Index + +## Project Overview + +- **Project:** PriceFlow +- **Type:** Multi-part (Frontend + Backend) +- **Primary Languages:** Python, JavaScript (React) +- **Architecture:** Client-Server / Service-Oriented +- **Status:** Brownfield Analysis (Quick Scan) + +## Quick Reference + +### Frontend (User Interface) + +- **Path:** `frontend/` +- **Tech:** React 18, Vite, Tailwind CSS +- **Documentation:** + - [Architecture](./architecture-frontend.md) + - [Development Guide](./development-guide.md) + +### Backend (API & Worker) + +- **Path:** `app/` +- **Tech:** FastAPI, Python 3.12, SQLAlchemy +- **Documentation:** + - [Architecture](./architecture-app.md) + - [API Contracts](./api-contracts-app.md) + - [Data Models](./data-models-app.md) + +## Generated Documentation + +- [Project Overview](./project-overview.md) +- [Source Tree Analysis](./source-tree-analysis.md) +- [Integration Architecture](./integration-architecture.md) +- [Deployment Guide](./deployment-guide.md) + +## Existing Documentation + +- [Amazon Scraper Details](./AMAZON_SCRAPER.md) +- [API Catalogues](./API_CATALOGUES.md) +- [Analysis Report](../RAPPORT_ANALYSE.md) +- [Startup Guide](../DEMARRAGE.md) + +## Getting Started + +1. **Setup**: Check the [Deployment Guide](./deployment-guide.md) to get running with Docker. +2. **Develop**: See the [Development Guide](./development-guide.md) for local setup instructions. +3. **Explore**: Review the [Source Tree Analysis](./source-tree-analysis.md) to understand the codebase structure. diff --git a/docs/integration-architecture.md b/docs/integration-architecture.md new file mode 100644 index 0000000..426abcf --- /dev/null +++ b/docs/integration-architecture.md @@ -0,0 +1,47 @@ +# Integration Architecture + +## System Overview + +PriceFlow operates as a distributed system with three main components interacting over the network: + +1. **Frontend (Client)**: React SPA running in the user's browser. +2. **Backend (API)**: Python FastAPI service. +3. **Browserless Service**: Headless Chrome instance. + +## Communication Patterns + +### Frontend ↔ Backend + +- **Protocol**: HTTP/REST +- **Format**: JSON +- **Authentication**: (To be determined - check auth middleware) +- **Endpoints**: Exposed via `app/routers` + +### Backend ↔ Database + +- **Protocol**: PostgreSQL Wire Protocol (TCP) +- **Driver**: `psycopg2-binary` / SQLAlchemy +- **Connection**: Persistent pool + +### Backend ↔ Browserless + +- **Protocol**: WebSocket +- **Library**: Playwright +- **Flow**: The backend connects to the remote browser to execute scraping scripts and retrieving page content/screenshots. + +### Backend ↔ External AI Providers + +- **Protocol**: HTTPS (API Calls) +- **Services**: OpenAI, Anthropic, OpenRouter, Ollama (Local/Network) +- **Library**: `litellm` + +## Data Flow Diagram (Conceptual) + +```mermaid +graph TD + User[User Browser] <-->|HTTP/REST| API[FastAPI Backend] + API <-->|SQL| DB[(PostgreSQL)] + API <-->|WebSocket| Chrome[Browserless] + API <-->|HTTPS| AI[AI Providers (OpenAI/Ollama)] + Chrome -->|HTTP| Web[Target Websites] +``` diff --git a/docs/project-overview.md b/docs/project-overview.md new file mode 100644 index 0000000..f4c0979 --- /dev/null +++ b/docs/project-overview.md @@ -0,0 +1,42 @@ +# PriceFlow + +**Suivi de prix intelligent propulsé par l'IA** + +## Executive Summary + +PriceFlow est une application auto-hébergée de suivi de prix qui utilise l'intelligence artificielle pour analyser visuellement les pages produits. Elle détecte les prix et l'état des stocks via des captures d'écran, supporte de multiples fournisseurs d'IA (OpenAI, Anthropic, Ollama, OpenRouter), et envoie des notifications via Apprise. + +## Technology Stack + +| Component | Technology | Details | +|-----------|------------|---------| +| **Frontend** | React 18 | Vite, Tailwind CSS, Radix UI, i18next | +| **Backend** | Python 3.12 | FastAPI, Uvicorn, SQLAlchemy | +| **Database** | PostgreSQL | Managed via Docker | +| **Scraping** | Playwright | Browserless service, Beautiful Soup 4, Crawl4AI | +| **AI** | LiteLLM | Supports OpenAI, Anthropic, Ollama, OpenRouter | +| **Infrastructure** | Docker | Docker Compose, Nginx (network) | + +## Architecture Type + +**Type:** Multi-part (Client/Server) +**Repository Type:** Monorepo/Multi-part structure + +The project is divided into two distinct parts: + +1. **Frontend**: A React-based Single Page Application (SPA). +2. **Backend**: A Python/FastAPI application acting as the API and worker service. + +## Key Features + +- **Visual AI Analysis**: Extracts price and stock from screenshots. +- **Multi-provider AI Support**: Flexible configuration for LLMs. +- **Smart Scrolling & History**: Historical tracking of price changes. +- **Multi-channel Notifications**: Discord, Telegram, Email via Apprise. +- **Dockerized Deployment**: Easy setup with Docker Compose. + +## Documentation Links + +- [Source Tree Analysis](./source-tree-analysis.md) +- [Development Guide](./development-guide.md) +- [Deployment Guide](./deployment-guide.md) diff --git a/docs/source-tree-analysis.md b/docs/source-tree-analysis.md new file mode 100644 index 0000000..9512d86 --- /dev/null +++ b/docs/source-tree-analysis.md @@ -0,0 +1,53 @@ +# Source Tree Analysis + +## Critical Directories + +``` +Priceflow/ +├── frontend/ # React Frontend Application (Part: frontend) +│ ├── public/ # Static assets (favicons, logos) +│ ├── src/ +│ │ ├── components/ # Reusable UI components (Radix UI, Custom) +│ │ ├── pages/ # Route components (Dashboard, Settings) +│ │ ├── hooks/ # Custom React hooks +│ │ ├── i18n/ # Internationalization configuration & locales +│ │ ├── lib/ # Utility libraries (utils, constants) +│ │ ├── App.jsx # Main React component +│ │ └── main.jsx # Application Entry Point +│ ├── package.json # Frontend dependencies & scripts +│ └── vite.config.js # Vite build configuration +├── app/ # FastAPI Backend Application (Part: app) +│ ├── routers/ # API Endpoints (separated by feature) +│ ├── services/ # Business logic & External integrations (AI, Scraping) +│ ├── core/ # Core configuration & config loading +│ ├── utils/ # General utilities +│ ├── alembic/ # Database migrations +│ ├── models.py # SQLAlchemy Database Models +│ ├── schemas.py # Pydantic Schemas (Request/Response) +│ └── main.py # Application Entry Point (FastAPI app) +├── docs/ # Project Documentation +├── tests/ # Test suite (Pytest) +├── scripts/ # Utility scripts (e.g. setup) +├── docker-compose.yml # Container orchestration config +├── Dockerfile # Backend container definition +├── init.sql # Database initialization script +└── README.md # Project Entry Documentation +``` + +## Entry Points + +- **Frontend**: `frontend/src/main.jsx` - Bootstraps the React application and mounts it to the DOM. +- **Backend**: `app/main.py` - Initializes the FastAPI application, mounts routers, and configures middleware. + +## Integration Points + +- **API Communication**: The frontend communicates with the backend via REST API calls. Axios is likely used as the HTTP client (from package.json). +- **Database**: The backend connects to the PostgreSQL database container defined in `docker-compose.yml`. +- **Scraping**: The backend connects to the `browserless` service via WebSocket (`ws://browserless:3000`) for Playwright operations. + +## Critical Files + +- `docker-compose.yml`: Defines the entire stack (App, DB, Browserless). +- `frontend/vite.config.js`: Controls the frontend build process. +- `app/core/config.py` (implied): Likely handles environment variables like `DATABASE_URL`, `OPENAI_API_KEY`. +- `app/models.py`: Defines the data structure (Price, Product, etc.). diff --git a/task.md b/task.md index 6806f87..79cb63a 100644 --- a/task.md +++ b/task.md @@ -1,21 +1,31 @@ -# Deep Debugging Action.com Availability +# Project Documentation Workflow ## Context -Some products on Action.com are still marked as unavailable even after the first round of fixes. +Running the `bmad-bmm-workflows-document-project` workflow to analyze and document the brownfield project "Priceflow". ## Current Focus -Identifying why specific Action.com products fail the availability check. +Workflow Complete. ## Master Plan -- [ ] List currently unavailable Action.com items from the database (if possible) or logs -- [ ] Reproduce the check for a specific problematic item -- [ ] Analyze the HTML and Title for these items -- [ ] Refine the matching logic or the unavailability detection -- [ ] Verify fix with multiple Action.com items +- [x] Locate `_bmad` resources +- [x] Load workflow engine and config +- [x] Execute workflow steps + - [x] Validate project status + - [x] Detemine scan mode (Initial/Quick) + - [x] **Step 1: Detect project structure & type** + - [x] **Step 2: Discover existing docs** + - [x] **Step 3: Analyze tech stack** + - [x] **Step 4: Conditional analysis** + - [x] **Step 5: Source tree analysis** + - [x] **Step 6-10: Generate artifacts** +- [x] Verify generated documentation +- [x] Update workflow status (`bmm-workflow-status.yaml`) ## Progress Log -- [/] Task started. +- [x] Classified project: Frontend (Web) + Backend (Python/FastAPI). +- [x] Generated full suite of documentation in `docs/`. +- [x] Updated project status.