# bottle-note/bottle-note-api-server architecture

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

- Interactive diagram: https://gitdiagram.com/bottle-note/bottle-note-api-server
- Repository: https://github.com/bottle-note/bottle-note-api-server

## Overview

BottleNote is a modular-monolith API for whiskey enthusiasts to discover bottles and share tasting experiences. The user-facing journey includes browsing bottle information and reviews, then recording ratings or reviews and managing a personal collection; follow-based discovery and tasting history are supporting branches. Admin APIs manage catalog and curation data, while scheduled batch jobs support popularity and reporting. The tree and excerpts identify these subsystems, but most controller-to-service wiring was not shown; uncertain connections are therefore dashed and uncited.

Main entry points: [`bottlenote-product-api/src/main/java/app/bottlenote`](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-product-api/src/main/java/app/bottlenote) (Product Endpoints), [`bottlenote-batch/src/main/java/app/batch/bottlenote`](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-batch/src/main/java/app/batch/bottlenote) (Scheduled Jobs), [`bottlenote-admin-api/src/main/kotlin/app/bottlenote`](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-admin-api/src/main/kotlin/app/bottlenote) (Admin Endpoints), [`bottlenote-product-api/src/main/java/app/bottlenote/alcohols/controller/AlcoholQueryController.java`](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-product-api/src/main/java/app/bottlenote/alcohols/controller/AlcoholQueryController.java) (Bottle Browsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Product API"]
  node_product_api["Product Endpoints"]
  node_alcohol_api["Bottle Browsing"]
  node_review_api["Review Endpoints"]
  node_auth_api["Account Access"]
end

subgraph group_domains["Bottle Experiences"]
  node_alcohol_query["Bottle Discovery"]
  node_review_service["Reviews<br/>[ReviewService.java]"]
  node_rating_service["Ratings"]
  node_history_service["Tasting History"]
  node_user_domain["Accounts and Follows"]
  node_curation["Curated Discovery"]
  node_banner_service["Active Banners"]
  node_mfds_service["Public MFDS Data"]
  node_rating_store[("Rating Records")]
  node_cursor_codec["Cursor Pagination"]
end

subgraph group_operations["Admin Operations"]
  node_admin_api["Admin Endpoints"]
  node_catalog_admin["Catalog Management"]
  node_admin_review["Review Moderation"]
end

subgraph group_insights["Background Insights"]
  node_batch["Scheduled Jobs"]
  node_popularity["Popularity Rollups"]
  node_best_reviews["Best Review Selection"]
  node_visitor_telemetry["Visitor Telemetry"]
end

node_visitor(("Whiskey Enthusiast"))

node_visitor -.->|"uses"| node_product_api
node_product_api -.->|"routes bottle queries"| node_alcohol_api
node_product_api -.->|"routes reviews"| node_review_api
node_product_api -.->|"routes account access"| node_auth_api
node_review_api -->|"calls"| node_review_service
node_alcohol_api -.->|"delegates queries"| node_alcohol_query
node_visitor -.->|"records ratings"| node_rating_service
node_visitor -.->|"views tasting history"| node_history_service
node_visitor -.->|"follows users"| node_user_domain
node_visitor -.->|"explores curation"| node_curation
node_visitor -.->|"views banners"| node_banner_service
node_visitor -.->|"searches public data"| node_mfds_service
node_rating_service -->|"reads ratings"| node_rating_store
node_alcohol_query -->|"verifies cursors"| node_cursor_codec
node_mfds_service -->|"encodes cursors"| node_cursor_codec
node_admin_api -.->|"routes catalog work"| node_catalog_admin
node_admin_api -.->|"routes moderation"| node_admin_review
node_admin_review -.->|"queries reviews"| node_review_service
node_batch -.->|"schedules rollups"| node_popularity
node_batch -.->|"schedules selection"| node_best_reviews
node_batch -.->|"consumes telemetry"| node_visitor_telemetry

click node_product_api "https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-product-api/src/main/java/app/bottlenote"
click node_alcohol_api "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-product-api/src/main/java/app/bottlenote/alcohols/controller/AlcoholQueryController.java"
click node_review_api "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-product-api/src/main/java/app/bottlenote/review/controller/ReviewController.java"
click node_auth_api "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-product-api/src/main/java/app/bottlenote/user/controller/AuthV2Controller.java"
click node_alcohol_query "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/alcohols/service/AlcoholQueryService.java"
click node_review_service "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/review/service/ReviewService.java"
click node_rating_service "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/rating/service/RatingQueryService.java"
click node_history_service "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/history/service/UserHistoryQueryService.java"
click node_user_domain "https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-mono/src/main/java/app/bottlenote/user"
click node_curation "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/curation/service/CurationSpecQueryService.java"
click node_admin_api "https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-admin-api/src/main/kotlin/app/bottlenote"
click node_catalog_admin "https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-admin-api/src/main/kotlin/app/bottlenote/alcohols/presentation"
click node_admin_review "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-admin-api/src/main/kotlin/app/bottlenote/review/presentation/AdminReviewController.kt"
click node_batch "https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-batch/src/main/java/app/batch/bottlenote"
click node_popularity "https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-batch/src/main/java/app/batch/bottlenote/job/popularity"
click node_best_reviews "https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-batch/src/main/java/app/batch/bottlenote/job/ranking"
click node_visitor_telemetry "https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-batch/src/main/java/app/batch/bottlenote/visitor"
click node_banner_service "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/banner/service/BannerQueryService.java"
click node_mfds_service "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/mfds/service/MfdsPublicQueryService.java"
click node_rating_store "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/rating/domain/RatingRepository.java"
click node_cursor_codec "https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/global/pagination/HmacCursorCodec.java"

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_product_api,node_alcohol_api,node_review_api,node_auth_api toneBlue
class node_alcohol_query,node_review_service,node_rating_service,node_history_service,node_user_domain,node_curation,node_banner_service,node_mfds_service,node_rating_store,node_cursor_codec toneAmber
class node_admin_api,node_catalog_admin,node_admin_review toneMint
class node_batch,node_popularity,node_best_reviews,node_visitor_telemetry toneRose
class node_visitor toneIndigo
```

## Components

### Product API

- [Product Endpoints](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-product-api/src/main/java/app/bottlenote): `bottlenote-product-api/src/main/java/app/bottlenote`
- [Bottle Browsing](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-product-api/src/main/java/app/bottlenote/alcohols/controller/AlcoholQueryController.java): `bottlenote-product-api/src/main/java/app/bottlenote/alcohols/controller/AlcoholQueryController.java`
- [Review Endpoints](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-product-api/src/main/java/app/bottlenote/review/controller/ReviewController.java): `bottlenote-product-api/src/main/java/app/bottlenote/review/controller/ReviewController.java`
- [Account Access](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-product-api/src/main/java/app/bottlenote/user/controller/AuthV2Controller.java): `bottlenote-product-api/src/main/java/app/bottlenote/user/controller/AuthV2Controller.java`

### Bottle Experiences

- [Bottle Discovery](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/alcohols/service/AlcoholQueryService.java): `bottlenote-mono/src/main/java/app/bottlenote/alcohols/service/AlcoholQueryService.java`
- [Reviews](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/review/service/ReviewService.java): `bottlenote-mono/src/main/java/app/bottlenote/review/service/ReviewService.java`
- [Ratings](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/rating/service/RatingQueryService.java): `bottlenote-mono/src/main/java/app/bottlenote/rating/service/RatingQueryService.java`
- [Tasting History](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/history/service/UserHistoryQueryService.java): `bottlenote-mono/src/main/java/app/bottlenote/history/service/UserHistoryQueryService.java`
- [Accounts and Follows](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-mono/src/main/java/app/bottlenote/user): `bottlenote-mono/src/main/java/app/bottlenote/user`
- [Curated Discovery](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/curation/service/CurationSpecQueryService.java): `bottlenote-mono/src/main/java/app/bottlenote/curation/service/CurationSpecQueryService.java`
- [Active Banners](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/banner/service/BannerQueryService.java): `bottlenote-mono/src/main/java/app/bottlenote/banner/service/BannerQueryService.java`
- [Public MFDS Data](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/mfds/service/MfdsPublicQueryService.java): `bottlenote-mono/src/main/java/app/bottlenote/mfds/service/MfdsPublicQueryService.java`
- [Rating Records](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/rating/domain/RatingRepository.java): `bottlenote-mono/src/main/java/app/bottlenote/rating/domain/RatingRepository.java`
- [Cursor Pagination](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-mono/src/main/java/app/bottlenote/global/pagination/HmacCursorCodec.java): `bottlenote-mono/src/main/java/app/bottlenote/global/pagination/HmacCursorCodec.java`

### Admin Operations

- [Admin Endpoints](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-admin-api/src/main/kotlin/app/bottlenote): `bottlenote-admin-api/src/main/kotlin/app/bottlenote`
- [Catalog Management](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-admin-api/src/main/kotlin/app/bottlenote/alcohols/presentation): `bottlenote-admin-api/src/main/kotlin/app/bottlenote/alcohols/presentation`
- [Review Moderation](https://github.com/bottle-note/bottle-note-api-server/blob/main/bottlenote-admin-api/src/main/kotlin/app/bottlenote/review/presentation/AdminReviewController.kt): `bottlenote-admin-api/src/main/kotlin/app/bottlenote/review/presentation/AdminReviewController.kt`

### Background Insights

- [Scheduled Jobs](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-batch/src/main/java/app/batch/bottlenote): `bottlenote-batch/src/main/java/app/batch/bottlenote`
- [Popularity Rollups](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-batch/src/main/java/app/batch/bottlenote/job/popularity): `bottlenote-batch/src/main/java/app/batch/bottlenote/job/popularity`
- [Best Review Selection](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-batch/src/main/java/app/batch/bottlenote/job/ranking): `bottlenote-batch/src/main/java/app/batch/bottlenote/job/ranking`
- [Visitor Telemetry](https://github.com/bottle-note/bottle-note-api-server/tree/main/bottlenote-batch/src/main/java/app/batch/bottlenote/visitor): `bottlenote-batch/src/main/java/app/batch/bottlenote/visitor`

### Other components

- **Whiskey Enthusiast**

## Connections

- Whiskey Enthusiast → Product Endpoints: uses
- Product Endpoints → Bottle Browsing: routes bottle queries (evidence: `bottlenote-product-api/src/main/java/app/bottlenote/alcohols/controller/AlcoholQueryController.java`)
- Product Endpoints → Review Endpoints: routes reviews (evidence: `bottlenote-product-api/src/main/java/app/bottlenote/review/controller/ReviewController.java`)
- Product Endpoints → Account Access: routes account access
- Review Endpoints → Reviews: calls (evidence: `bottlenote-product-api/src/main/java/app/bottlenote/review/controller/ReviewController.java`)
- Bottle Browsing → Bottle Discovery: delegates queries (evidence: `bottlenote-product-api/src/main/java/app/bottlenote/alcohols/controller/AlcoholQueryController.java`)
- Whiskey Enthusiast → Ratings: records ratings
- Whiskey Enthusiast → Tasting History: views tasting history
- Whiskey Enthusiast → Accounts and Follows: follows users
- Whiskey Enthusiast → Curated Discovery: explores curation
- Whiskey Enthusiast → Active Banners: views banners
- Whiskey Enthusiast → Public MFDS Data: searches public data
- Ratings → Rating Records: reads ratings (evidence: `bottlenote-mono/src/main/java/app/bottlenote/rating/service/RatingQueryService.java`)
- Bottle Discovery → Cursor Pagination: verifies cursors (evidence: `bottlenote-mono/src/main/java/app/bottlenote/alcohols/service/AlcoholQueryService.java`)
- Public MFDS Data → Cursor Pagination: encodes cursors (evidence: `bottlenote-mono/src/main/java/app/bottlenote/mfds/service/MfdsPublicQueryService.java`)
- Admin Endpoints → Catalog Management: routes catalog work (evidence: `bottlenote-admin-api/src/main/kotlin/app/bottlenote/alcohols/presentation/AdminAlcoholAttributeController.kt`)
- Admin Endpoints → Review Moderation: routes moderation (evidence: `bottlenote-admin-api/src/main/kotlin/app/bottlenote/review/presentation/AdminReviewController.kt`)
- Review Moderation → Reviews: queries reviews
- Scheduled Jobs → Popularity Rollups: schedules rollups
- Scheduled Jobs → Best Review Selection: schedules selection
- Scheduled Jobs → Visitor Telemetry: consumes telemetry