# ursusz/essenza architecture

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

- Interactive diagram: https://gitdiagram.com/ursusz/essenza
- Repository: https://github.com/ursusz/essenza

## Overview

Essenza is a perfume-focused web app whose documented capabilities include visual scanning, perfume catalog and community scores, anti-counterfeit guidance, a personal wardrobe, and gamification. Its principal scan workflow is intended to take a user image through API scan handling and an S3-triggered processor, then return recognition results through an internal callback. Most domain modules are represented only by directory structure, and the scan processor is explicitly unfinished; the graph therefore distinguishes documented structure from unverified runtime connections.

Main entry points: [`api/src/main/java/ro/unibuc/essenza/EssenzaApplication.java`](https://github.com/ursusz/essenza/blob/dev/api/src/main/java/ro/unibuc/essenza/EssenzaApplication.java) (API application), [`web/src/App.tsx`](https://github.com/ursusz/essenza/blob/dev/web/src/App.tsx) (PWA interface), [`api/src/main/java/ro/unibuc/essenza/scan`](https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/scan) (Scan decisions), [`scan-processor/app/handler.py`](https://github.com/ursusz/essenza/blob/dev/scan-processor/app/handler.py) (Image processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["PWA interface<br/>[App.tsx]"]
  node_appstart["Web entry point<br/>[main.tsx]"]
end

subgraph group_api["Spring API"]
  node_apiapp["API application"]
  node_auth["Accounts and JWT"]
  node_scanapi["Scan decisions"]
  node_catalog["Perfume catalog"]
  node_reviews["Reviews and scores"]
  node_authenticity["Authenticity checks"]
  node_wardrobe["Personal wardrobe"]
  node_gamification["Gamification"]
  node_articles["Influencer articles"]
end

subgraph group_scan["Scan processing"]
  node_s3[("Scan object store")]
  node_processor["Image processor<br/>[handler.py]"]
end

subgraph group_catalogdata["Catalog and data"]
  node_ingest["Catalog ingestion<br/>[__main__.py]"]
  node_db[("Application database")]
end

node_user(("Perfume user"))

node_appstart -->|"renders"| node_web
node_user -.->|"uses"| node_web
node_web -.->|"API requests"| node_apiapp
node_apiapp -.->|"routes scans"| node_scanapi
node_scanapi -.->|"uploads scans"| node_s3
node_s3 -->|"object-created event"| node_processor
node_processor -.->|"recognition callback"| node_scanapi
node_apiapp -.->|"provides security"| node_auth
node_apiapp -.->|"serves catalog"| node_catalog
node_apiapp -.->|"serves reviews"| node_reviews
node_apiapp -.->|"serves checks"| node_authenticity
node_apiapp -.->|"serves wardrobe"| node_wardrobe
node_apiapp -.->|"serves features"| node_gamification
node_apiapp -.->|"serves articles"| node_articles
node_ingest -.->|"loads catalog"| node_catalog
node_apiapp -.->|"persists data"| node_db

click node_web "https://github.com/ursusz/essenza/blob/dev/web/src/App.tsx"
click node_appstart "https://github.com/ursusz/essenza/blob/dev/web/src/main.tsx"
click node_apiapp "https://github.com/ursusz/essenza/blob/dev/api/src/main/java/ro/unibuc/essenza/EssenzaApplication.java"
click node_auth "https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/auth"
click node_scanapi "https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/scan"
click node_catalog "https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/catalog"
click node_reviews "https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/review"
click node_authenticity "https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/authenticity"
click node_wardrobe "https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/wardrobe"
click node_gamification "https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/gamification"
click node_articles "https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/article"
click node_processor "https://github.com/ursusz/essenza/blob/dev/scan-processor/app/handler.py"
click node_ingest "https://github.com/ursusz/essenza/blob/dev/ingest/ingest/__main__.py"
click node_db "https://github.com/ursusz/essenza/tree/dev/api/src/main/resources/db/migration"

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_web,node_appstart,node_user toneBlue
class node_apiapp,node_auth,node_scanapi,node_catalog,node_reviews,node_authenticity,node_wardrobe,node_gamification,node_articles toneAmber
class node_s3,node_processor toneMint
class node_ingest,node_db toneRose
```

## Components

### Web client

- [PWA interface](https://github.com/ursusz/essenza/blob/dev/web/src/App.tsx): `web/src/App.tsx`
- [Web entry point](https://github.com/ursusz/essenza/blob/dev/web/src/main.tsx): `web/src/main.tsx`

### Spring API

- [API application](https://github.com/ursusz/essenza/blob/dev/api/src/main/java/ro/unibuc/essenza/EssenzaApplication.java): `api/src/main/java/ro/unibuc/essenza/EssenzaApplication.java`
- [Accounts and JWT](https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/auth): `api/src/main/java/ro/unibuc/essenza/auth`
- [Scan decisions](https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/scan): `api/src/main/java/ro/unibuc/essenza/scan`
- [Perfume catalog](https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/catalog): `api/src/main/java/ro/unibuc/essenza/catalog`
- [Reviews and scores](https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/review): `api/src/main/java/ro/unibuc/essenza/review`
- [Authenticity checks](https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/authenticity): `api/src/main/java/ro/unibuc/essenza/authenticity`
- [Personal wardrobe](https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/wardrobe): `api/src/main/java/ro/unibuc/essenza/wardrobe`
- [Gamification](https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/gamification): `api/src/main/java/ro/unibuc/essenza/gamification`
- [Influencer articles](https://github.com/ursusz/essenza/tree/dev/api/src/main/java/ro/unibuc/essenza/article): `api/src/main/java/ro/unibuc/essenza/article`

### Scan processing

- **Scan object store**
- [Image processor](https://github.com/ursusz/essenza/blob/dev/scan-processor/app/handler.py): `scan-processor/app/handler.py`

### Catalog and data

- [Catalog ingestion](https://github.com/ursusz/essenza/blob/dev/ingest/ingest/__main__.py): `ingest/ingest/__main__.py`
- [Application database](https://github.com/ursusz/essenza/tree/dev/api/src/main/resources/db/migration): `api/src/main/resources/db/migration`

### Other components

- **Perfume user**

## Connections

- Web entry point → PWA interface: renders (evidence: `web/src/main.tsx`)
- Perfume user → PWA interface: uses
- PWA interface → API application: API requests
- API application → Scan decisions: routes scans
- Scan decisions → Scan object store: uploads scans (evidence: `README.md`)
- Scan object store → Image processor: object-created event (evidence: `scan-processor/app/handler.py`)
- Image processor → Scan decisions: recognition callback (evidence: `README.md`)
- API application → Accounts and JWT: provides security (evidence: `README.md`)
- API application → Perfume catalog: serves catalog (evidence: `README.md`)
- API application → Reviews and scores: serves reviews (evidence: `README.md`)
- API application → Authenticity checks: serves checks (evidence: `README.md`)
- API application → Personal wardrobe: serves wardrobe (evidence: `README.md`)
- API application → Gamification: serves features (evidence: `README.md`)
- API application → Influencer articles: serves articles (evidence: `README.md`)
- Catalog ingestion → Perfume catalog: loads catalog (evidence: `ingest/ingest/__main__.py`)
- API application → Application database: persists data
