# jeypraveen/photoscore-engine architecture

> Architecture diagram of the GitHub repository jeypraveen/photoscore-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeypraveen/photoscore-engine
- Repository: https://github.com/jeypraveen/photoscore-engine

## Overview

PhotoScore is a multilingual product-photo quality checker exposed through a WhatsApp bot and a direct analysis API. The principal workflow accepts a product image, checks usage eligibility, retrieves and decodes the image, computes quality and marketplace-compliance scores, and returns a localized report. The WhatsApp route also supports language and marketplace preferences; payment webhooks activate paid plans, while admin statistics read usage data. The README contains only the product name, so capability details and relationships here rely on the supplied source excerpts; some implementation is unsampled.

Main entry points: [`app/main.py`](https://github.com/jeypraveen/photoscore-engine/blob/main/app/main.py) (FastAPI routes), [`app/cv_engine.py`](https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py) (Photo analysis), [`app/whatsapp.py`](https://github.com/jeypraveen/photoscore-engine/blob/main/app/whatsapp.py) (WhatsApp integration), [`app/database.py`](https://github.com/jeypraveen/photoscore-engine/blob/main/app/database.py) (Supabase database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and messaging"]
  node_fastapi["FastAPI routes<br/>[main.py]"]
  node_wa_adapter["WhatsApp integration<br/>[whatsapp.py]"]
end

subgraph group_analysis["Photo analysis"]
  node_image_decode["Image decoding<br/>[cv_engine.py]"]
  node_analysis_orchestrator["Photo analysis<br/>[cv_engine.py]"]
  node_background["Background check<br/>[cv_engine.py]"]
  node_framing["Product framing<br/>[cv_engine.py]"]
  node_sharpness["Sharpness check<br/>[cv_engine.py]"]
  node_lighting["Lighting check<br/>[cv_engine.py]"]
  node_text_check["Text detection<br/>[cv_engine.py]"]
  node_marketplace_rules["Marketplace compliance<br/>[cv_engine.py]"]
end

subgraph group_accounts["Accounts and billing"]
  node_supabase[("Supabase database<br/>[database.py]")]
  node_user_account["User preferences<br/>[database.py]"]
  node_usage_limits["Usage and limits<br/>[database.py]"]
  node_payment_activation["Paid plan activation<br/>[main.py]"]
end

subgraph group_presentation["Localization"]
  node_translations["Language messages<br/>[languages.py]"]
  node_report["Score report formatting<br/>[languages.py]"]
end

node_seller(("Photo seller"))
node_api_user(("API client"))
node_admin(("Admin"))
node_meta{{"WhatsApp Cloud API"}}
node_razorpay{{"Razorpay"}}

node_seller -->|"sends photo"| node_meta
node_meta -->|"delivers webhook"| node_fastapi
node_fastapi -->|"extracts message"| node_wa_adapter
node_fastapi -->|"loads or updates"| node_user_account
node_fastapi -->|"checks eligibility"| node_usage_limits
node_fastapi -->|"downloads media"| node_wa_adapter
node_wa_adapter -->|"fetches media"| node_meta
node_fastapi -->|"decodes image"| node_image_decode
node_image_decode -->|"provides image"| node_analysis_orchestrator
node_fastapi -->|"analyzes API image"| node_analysis_orchestrator
node_analysis_orchestrator -->|"runs check"| node_background
node_analysis_orchestrator -->|"runs check"| node_framing
node_analysis_orchestrator -->|"runs check"| node_sharpness
node_analysis_orchestrator -->|"runs check"| node_lighting
node_analysis_orchestrator -->|"runs check"| node_text_check
node_analysis_orchestrator -->|"checks compliance"| node_marketplace_rules
node_fastapi -->|"records usage"| node_usage_limits
node_fastapi -->|"formats result"| node_report
node_report -->|"gets messages"| node_translations
node_fastapi -->|"sends reply"| node_wa_adapter
node_wa_adapter -->|"sends message"| node_meta
node_fastapi -->|"handles payment event"| node_payment_activation
node_razorpay -->|"posts payment webhook"| node_fastapi
node_payment_activation -->|"activates plan"| node_user_account
node_fastapi -->|"requests account and usage data"| node_supabase
node_user_account -->|"reads and writes users"| node_supabase
node_usage_limits -->|"reads and writes usage"| node_supabase
node_api_user -->|"uploads image"| node_fastapi
node_admin -->|"requests statistics"| node_fastapi
node_fastapi -->|"reads statistics"| node_supabase

click node_fastapi "https://github.com/jeypraveen/photoscore-engine/blob/main/app/main.py"
click node_wa_adapter "https://github.com/jeypraveen/photoscore-engine/blob/main/app/whatsapp.py"
click node_image_decode "https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py"
click node_analysis_orchestrator "https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py"
click node_background "https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py"
click node_framing "https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py"
click node_sharpness "https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py"
click node_lighting "https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py"
click node_text_check "https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py"
click node_marketplace_rules "https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py"
click node_supabase "https://github.com/jeypraveen/photoscore-engine/blob/main/app/database.py"
click node_user_account "https://github.com/jeypraveen/photoscore-engine/blob/main/app/database.py"
click node_usage_limits "https://github.com/jeypraveen/photoscore-engine/blob/main/app/database.py"
click node_payment_activation "https://github.com/jeypraveen/photoscore-engine/blob/main/app/main.py"
click node_translations "https://github.com/jeypraveen/photoscore-engine/blob/main/app/languages.py"
click node_report "https://github.com/jeypraveen/photoscore-engine/blob/main/app/languages.py"

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_fastapi,node_wa_adapter,node_api_user toneBlue
class node_image_decode,node_analysis_orchestrator,node_background,node_framing,node_sharpness,node_lighting,node_text_check,node_marketplace_rules toneAmber
class node_supabase,node_user_account,node_usage_limits,node_payment_activation,node_meta toneMint
class node_translations,node_report toneRose
class node_seller,node_admin,node_razorpay toneIndigo
```

## Components

### Entry and messaging

- [FastAPI routes](https://github.com/jeypraveen/photoscore-engine/blob/main/app/main.py): `app/main.py`
- [WhatsApp integration](https://github.com/jeypraveen/photoscore-engine/blob/main/app/whatsapp.py): `app/whatsapp.py`

### Photo analysis

- [Image decoding](https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py): `app/cv_engine.py`
- [Photo analysis](https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py): `app/cv_engine.py`
- [Background check](https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py): `app/cv_engine.py`
- [Product framing](https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py): `app/cv_engine.py`
- [Sharpness check](https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py): `app/cv_engine.py`
- [Lighting check](https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py): `app/cv_engine.py`
- [Text detection](https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py): `app/cv_engine.py`
- [Marketplace compliance](https://github.com/jeypraveen/photoscore-engine/blob/main/app/cv_engine.py): `app/cv_engine.py`

### Accounts and billing

- [Supabase database](https://github.com/jeypraveen/photoscore-engine/blob/main/app/database.py): `app/database.py`
- [User preferences](https://github.com/jeypraveen/photoscore-engine/blob/main/app/database.py): `app/database.py`
- [Usage and limits](https://github.com/jeypraveen/photoscore-engine/blob/main/app/database.py): `app/database.py`
- [Paid plan activation](https://github.com/jeypraveen/photoscore-engine/blob/main/app/main.py): `app/main.py`

### Localization

- [Language messages](https://github.com/jeypraveen/photoscore-engine/blob/main/app/languages.py): `app/languages.py`
- [Score report formatting](https://github.com/jeypraveen/photoscore-engine/blob/main/app/languages.py): `app/languages.py`

### Other components

- **Photo seller**
- **API client**
- **Admin**
- **WhatsApp Cloud API**
- **Razorpay**

## Connections

- Photo seller → WhatsApp Cloud API: sends photo
- WhatsApp Cloud API → FastAPI routes: delivers webhook
- FastAPI routes → WhatsApp integration: extracts message
- FastAPI routes → User preferences: loads or updates
- FastAPI routes → Usage and limits: checks eligibility
- FastAPI routes → WhatsApp integration: downloads media
- WhatsApp integration → WhatsApp Cloud API: fetches media
- FastAPI routes → Image decoding: decodes image
- Image decoding → Photo analysis: provides image
- FastAPI routes → Photo analysis: analyzes API image
- Photo analysis → Background check: runs check
- Photo analysis → Product framing: runs check
- Photo analysis → Sharpness check: runs check
- Photo analysis → Lighting check: runs check
- Photo analysis → Text detection: runs check
- Photo analysis → Marketplace compliance: checks compliance
- FastAPI routes → Usage and limits: records usage
- FastAPI routes → Score report formatting: formats result
- Score report formatting → Language messages: gets messages
- FastAPI routes → WhatsApp integration: sends reply
- WhatsApp integration → WhatsApp Cloud API: sends message
- FastAPI routes → Paid plan activation: handles payment event
- Razorpay → FastAPI routes: posts payment webhook
- Paid plan activation → User preferences: activates plan
- FastAPI routes → Supabase database: requests account and usage data
- User preferences → Supabase database: reads and writes users
- Usage and limits → Supabase database: reads and writes usage
- API client → FastAPI routes: uploads image
- Admin → FastAPI routes: requests statistics
- FastAPI routes → Supabase database: reads statistics