# bhagat2678/coffee-bean architecture

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

- Interactive diagram: https://gitdiagram.com/bhagat2678/coffee-bean
- Repository: https://github.com/bhagat2678/coffee-bean

## Overview

Coffee Bean Detection & Analysis is an image-based bean inspection product, exposed primarily through a Flask web app. Users provide front and optionally back images (and sample weight); the app detects and measures objects, derives quality and size results, and optionally matches beans across views before returning results for display. A CLI provides a separate single-image analysis route. The README documents calibration, color analysis, defect classification, and ArcFace mapping; excerpts do not show every implementation detail, so uncertain internal wiring is omitted.

Main entry points: [`website/app.py`](https://github.com/bhagat2678/coffee-bean/blob/main/website/app.py) (Flask analysis API), [`main.py`](https://github.com/bhagat2678/coffee-bean/blob/main/main.py) (Single-image CLI), [`website/static/js/app.js`](https://github.com/bhagat2678/coffee-bean/blob/main/website/static/js/app.js) (Upload and results UI), [`src/detector.py`](https://github.com/bhagat2678/coffee-bean/blob/main/src/detector.py) (Object detection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_webui["Upload and results UI<br/>[app.js]"]
  node_webapp["Flask analysis API<br/>[app.py]"]
  node_cli["Single-image CLI<br/>[main.py]"]
end

subgraph group_vision["Image Analysis"]
  node_detector["Object detection<br/>[detector.py]"]
  node_model["YOLO model weights<br/>[best.pt]"]
  node_analyzer["Color and size analysis<br/>[analyzer.py]"]
  node_shape["Bean shape metrics<br/>[shape_analyzer.py]"]
end

subgraph group_grading["Quality Analysis"]
  node_grading["Grade and size statistics<br/>[grading.py]"]
end

subgraph group_matching["Bean Matching"]
  node_arcface["Front-back matching<br/>[arcface.py]"]
end

node_user(("Coffee analyst"))
node_results["Analysis results"]

node_user -->|"uploads images"| node_webui
node_webui -->|"submits analysis"| node_webapp
node_webapp -->|"detects objects"| node_detector
node_detector -->|"loads weights"| node_model
node_webapp -->|"computes grades"| node_grading
node_webapp -.->|"matches views"| node_arcface
node_webapp -->|"returns analysis"| node_results
node_results -->|"renders results"| node_webui
node_user -->|"selects image"| node_cli
node_cli -->|"analyzes image"| node_analyzer
node_analyzer -->|"detects beans"| node_detector
node_cli -->|"prints summary"| node_results

click node_webui "https://github.com/bhagat2678/coffee-bean/blob/main/website/static/js/app.js"
click node_webapp "https://github.com/bhagat2678/coffee-bean/blob/main/website/app.py"
click node_cli "https://github.com/bhagat2678/coffee-bean/blob/main/main.py"
click node_detector "https://github.com/bhagat2678/coffee-bean/blob/main/src/detector.py"
click node_model "https://github.com/bhagat2678/coffee-bean/blob/main/models/best.pt"
click node_analyzer "https://github.com/bhagat2678/coffee-bean/blob/main/src/analyzer.py"
click node_shape "https://github.com/bhagat2678/coffee-bean/blob/main/src/shape_analyzer.py"
click node_grading "https://github.com/bhagat2678/coffee-bean/blob/main/src/grading.py"
click node_arcface "https://github.com/bhagat2678/coffee-bean/blob/main/src/arcface.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_webui,node_webapp,node_cli toneBlue
class node_detector,node_model,node_analyzer,node_shape toneAmber
class node_grading toneMint
class node_arcface toneRose
class node_user,node_results toneIndigo
```

## Components

### User Interfaces

- [Upload and results UI](https://github.com/bhagat2678/coffee-bean/blob/main/website/static/js/app.js): `website/static/js/app.js`
- [Flask analysis API](https://github.com/bhagat2678/coffee-bean/blob/main/website/app.py): `website/app.py`
- [Single-image CLI](https://github.com/bhagat2678/coffee-bean/blob/main/main.py): `main.py`

### Image Analysis

- [Object detection](https://github.com/bhagat2678/coffee-bean/blob/main/src/detector.py): `src/detector.py`
- [YOLO model weights](https://github.com/bhagat2678/coffee-bean/blob/main/models/best.pt): `models/best.pt`
- [Color and size analysis](https://github.com/bhagat2678/coffee-bean/blob/main/src/analyzer.py): `src/analyzer.py`
- [Bean shape metrics](https://github.com/bhagat2678/coffee-bean/blob/main/src/shape_analyzer.py): `src/shape_analyzer.py`

### Quality Analysis

- [Grade and size statistics](https://github.com/bhagat2678/coffee-bean/blob/main/src/grading.py): `src/grading.py`

### Bean Matching

- [Front-back matching](https://github.com/bhagat2678/coffee-bean/blob/main/src/arcface.py): `src/arcface.py`

### Other components

- **Coffee analyst**
- **Analysis results**

## Connections

- Coffee analyst → Upload and results UI: uploads images
- Upload and results UI → Flask analysis API: submits analysis
- Flask analysis API → Object detection: detects objects
- Object detection → YOLO model weights: loads weights
- Flask analysis API → Grade and size statistics: computes grades
- Flask analysis API → Front-back matching: matches views
- Flask analysis API → Analysis results: returns analysis
- Analysis results → Upload and results UI: renders results
- Coffee analyst → Single-image CLI: selects image
- Single-image CLI → Color and size analysis: analyzes image
- Color and size analysis → Object detection: detects beans
- Single-image CLI → Analysis results: prints summary