# junpatch/pricealert architecture

> Architecture diagram of the GitHub repository junpatch/pricealert, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/junpatch/pricealert
- Repository: https://github.com/junpatch/pricealert

## Overview

##### Project Type and Purpose
- PriceAlert is a full-stack e-commerce price-tracking application.
- Frontend: React + TypeScript (Vite) SPA for user interaction, product management, graphs, QR scanning.
- Backend: Django REST API with modular apps (accounts, products, notifications), Celery for async tasks, PostgreSQL for persistence, Redis as broker.
- Purpose: Let users register product URLs, define price-drop alerts, run periodic scraping, generate and send notifications via email.

##### File Structure & Architectural Patterns
- Two top-level directories: `/frontend` and `/backend`.
- Backend follows Django’s project-app structure (PriceAlert project + three apps).
- Uses MVC (Django Models, Views, Serializers as Controllers) and command pattern for Celery beat setup.
- Frontend organized by feature slices (Redux Toolkit), hooks, common components, pages.
- Asynchronous processing via Celery (Beat + Worker), external scrapers, notification services.
- Deployment artifacts: Dockerfile, docker-compose.dev.yml, Render blueprint (render.yaml), Vercel config.

##### Detailed Component Breakdown
- Accounts app (authentication endpoints)
- Products app (connectors, services, tasks)
- Notifications app (serializers, tasks, email templates)
- Management command `setup_periodic_tasks` as an initialization step.
- Template rendering for password reset emails.
- In async layer, call out three scheduled tasks: fetch_and_store_prices, check_price_alerts, send_price_alert_notifications.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        UI["React UI<br/>SPA"]:::frontend
        Main["main.tsx"]:::frontend
        App["App.tsx"]:::frontend
        Pages["Pages<br/>(Routing & Layout)"]:::frontend
        Common["Common Components"]:::frontend
        EC["EC Site Logos<br/>& Scanner"]:::frontend
        Store["Redux Store"]:::frontend
        Slices["Global & Feature Slices"]:::frontend
        Hooks["Feature Hooks"]:::frontend
        APIService["API Service Module"]:::frontend
        Utils["Utility Functions"]:::frontend

        UI -->|renders| App
        Main -->|bootstraps| UI
        App --> Pages
        App --> Common
        Common --> EC
        UI --> Store
        Store --> Slices
        Slices --> Hooks
        UI --> APIService
        APIService --> Utils
    end

    %% Backend Synchronous Layer
    subgraph "Backend (Django Monolith)"
        direction TB
        Settings["Settings & URLs"]:::backend
        CeleryConfig["Celery Config"]:::backend
        PeriodicCmd["setup_periodic_tasks<br/>(Management Command)"]:::backend

        subgraph "Accounts App"
            direction TB
            Accounts["accounts/ (models, views,<br/>serializers, urls)"]:::backend
        end
        subgraph "Products App"
            direction TB
            Connectors["connectors/"]:::backend
            Services["services/"]:::backend
            ProdTasks["tasks.py"]:::backend
        end
        subgraph "Notifications App"
            direction TB
            NotificationsAPI["notifications/"]:::backend
            NotifServices["services.py"]:::backend
            NotifTasks["tasks.py"]:::backend
        end

        Settings --> Accounts
        Settings --> Products
        Settings --> NotificationsAPI
        Settings --> CeleryConfig
        CeleryConfig --> PeriodicCmd
    end

    %% Async Layer
    subgraph "Async (Celery)"
        direction TB
        Beat["Celery Beat<br/>(Scheduler)"]:::async
        Broker["Redis Broker"]:::infra
        Worker["Celery Worker(s)"]:::async
        Scrapers["Scraping Tasks"]:::async
        AlertChecker["Alert Checker Task"]:::async
        Notifier["Notification Sender Task"]:::async

        Beat -->|schedules| Broker
        Worker -->|fetch tasks| Broker
        Worker --> Scrapers
        Worker --> AlertChecker
        Worker --> Notifier
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Postgres[(PostgreSQL DB)]:::infra
        Redis[(Redis Cache)]:::infra
        SMTP["SMTP Server"]:::infra
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Amazon["Amazon PA-API"]:::external
        EcommerceSites["E-commerce Sites"]:::external
    end

    %% Data Flows
    UI -->|POST /api/products| Settings
    Settings -->|CRUD| Postgres
    Settings -->|register task| Broker
    Scrapers -->|fetch prices| EcommerceSites
    Scrapers -->|use connectors| Connectors
    Scrapers -->|store prices| Postgres
    AlertChecker -->|read prices & alerts| Postgres
    AlertChecker -->|create notifications| Postgres
    Notifier -->|send email| SMTP
    Notifier -->|email content| NotificationsAPI
    APIService -->|GET /api/notifications| NotificationsAPI

    %% Click Events - Frontend
    click UI "https://github.com/junpatch/pricealert/tree/main/frontend/src"
    click Main "https://github.com/junpatch/pricealert/blob/main/frontend/src/main.tsx"
    click App "https://github.com/junpatch/pricealert/blob/main/frontend/src/App.tsx"
    click Pages "https://github.com/junpatch/pricealert/tree/main/frontend/src/pages"
    click Common "https://github.com/junpatch/pricealert/tree/main/frontend/src/components/common"
    click EC "https://github.com/junpatch/pricealert/tree/main/frontend/src/components/ec-sites"
    click Common "https://github.com/junpatch/pricealert/blob/main/frontend/src/components/common/QrCodeScanner.tsx"
    click Store "https://github.com/junpatch/pricealert/blob/main/frontend/src/store/index.ts"
    click Slices "https://github.com/junpatch/pricealert/tree/main/frontend/src/store/slices"
    click Hooks "https://github.com/junpatch/pricealert/tree/main/frontend/src/features/*/hooks"
    click APIService "https://github.com/junpatch/pricealert/blob/main/frontend/src/services/api.ts"
    click Utils "https://github.com/junpatch/pricealert/tree/main/frontend/src/utils"
    click Pages "https://github.com/junpatch/pricealert/blob/main/frontend/src/components/common/QrCodeScanner.tsx"
    click APIService "https://github.com/junpatch/pricealert/blob/main/frontend/src/services/api.ts"
    click Pages "https://github.com/junpatch/pricealert/blob/main/frontend/vercel.json"

    %% Click Events - Backend
    click Settings "https://github.com/junpatch/pricealert/blob/main/backend/PriceAlert/PriceAlert/settings.py"
    click Settings "https://github.com/junpatch/pricealert/blob/main/backend/PriceAlert/PriceAlert/urls.py"
    click CeleryConfig "https://github.com/junpatch/pricealert/blob/main/backend/PriceAlert/PriceAlert/celery.py"
    click PeriodicCmd "https://github.com/junpatch/pricealert/blob/main/backend/PriceAlert/PriceAlert/management/commands/setup_periodic_tasks.py"
    click Accounts "https://github.com/junpatch/pricealert/tree/main/backend/PriceAlert/accounts"
    click Connectors "https://github.com/junpatch/pricealert/tree/main/backend/PriceAlert/products/connectors"
    click Services "https://github.com/junpatch/pricealert/tree/main/backend/PriceAlert/products/services"
    click ProdTasks "https://github.com/junpatch/pricealert/blob/main/backend/PriceAlert/products/tasks.py"
    click NotificationsAPI "https://github.com/junpatch/pricealert/tree/main/backend/PriceAlert/notifications"
    click NotifServices "https://github.com/junpatch/pricealert/blob/main/backend/PriceAlert/notifications/services.py"
    click NotifTasks "https://github.com/junpatch/pricealert/blob/main/backend/PriceAlert/notifications/tasks.py"
    click Postgres "https://github.com/junpatch/pricealert/blob/main/backend/docker-compose.dev.yml"
    click Postgres "https://github.com/junpatch/pricealert/blob/main/render.yaml"
    click Redis "https://github.com/junpatch/pricealert/blob/main/backend/docker-compose.dev.yml"
    click SMTP "https://github.com/junpatch/pricealert/blob/main/backend/.env.example"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#037FFC,color:#000;
    classDef backend fill:#DFF7E0,stroke:#2E7D32,color:#000;
    classDef async fill:#FFE6A3,stroke:#F9A825,color:#000;
    classDef infra fill:#E0E0E0,stroke:#616161,color:#000;
    classDef external fill:#F3E5F5,stroke:#8E24AA,color:#000;
```
