# juliu9/it-project architecture

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

- Interactive diagram: https://gitdiagram.com/juliu9/it-project
- Repository: https://github.com/juliu9/it-project

## Overview

RecommenderAgent turns natural-language audiobook requests into structured intents, coordinates session-aware recommendation work, retrieves and ranks catalogue candidates, and returns conversational results. A separate book-search endpoint provides direct catalogue lookup. Redis supports conversational state, PostgreSQL stores long-term profiles, and Solr provides catalogue search. The sampled engine shows recommendation dispatch, candidate retrieval/ranking, and asynchronous session-update events; some gateway, profile, and response wiring is supported by the README rather than sampled implementation.

Main entry points: [`src/main/java/com/gen3/recommenderagent/engine/RecommendationEngine.java`](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/engine/RecommendationEngine.java) (Recommendation engine), [`src/main/java/com/gen3/recommenderagent/api/RequestGateway.java`](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/api/RequestGateway.java) (Request gateway), [`src/main/java/com/gen3/recommenderagent/inputparser/InputParser.java`](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/inputparser/InputParser.java) (Input parser), [`src/main/java/com/gen3/recommenderagent/api/BookSearchController.java`](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/api/BookSearchController.java) (Book search controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request handling"]
  node_gateway["Request gateway"]
  node_parser["Input parser<br/>[InputParser.java]"]
  node_sessionrequest["Parsed request"]
end

subgraph group_recommendation["Recommendation workflow"]
  node_engine["Recommendation engine"]
  node_retriever["Candidate retriever"]
  node_ranker["Ranking service"]
  node_recommendations["Recommendations"]
end

subgraph group_state["Session and profile state"]
  node_sessioncache["Session cache"]
  node_redis[("Redis")]
  node_sessionevent["Session update event"]
  node_observer["Redis session observer"]
  node_profiledb["User profile database<br/>[UserProfileDB.java]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_catalogue["Audiobook catalogue"]
  node_booksearch["Book search controller"]
  node_solrrepo["Solr audiobook repository"]
  node_solr[("Apache Solr")]
  node_searchresponse["Book search response"]
end

subgraph group_response["Response generation"]
  node_responsegen["Response generator"]
  node_llm(("AI model service"))
end

node_user(("API user"))

node_user -->|"submits request"| node_gateway
node_gateway -->|"parses text"| node_parser
node_parser -.->|"extracts intent"| node_llm
node_parser -->|"creates request"| node_sessionrequest
node_gateway -->|"processes request"| node_engine
node_engine -->|"reads session"| node_sessioncache
node_sessioncache -->|"reads/writes"| node_redis
node_engine -->|"retrieves candidates"| node_retriever
node_retriever -->|"searches catalogue"| node_solrrepo
node_solrrepo -->|"queries books"| node_solr
node_engine -->|"ranks candidates"| node_ranker
node_ranker -->|"creates results"| node_recommendations
node_engine -->|"publishes update"| node_sessionevent
node_sessionevent -->|"notifies listener"| node_observer
node_observer -->|"updates session"| node_sessioncache
node_engine -->|"uses profile"| node_profiledb
node_profiledb -->|"reads/writes profile"| node_postgres
node_gateway -->|"generates reply"| node_responsegen
node_responsegen -.->|"generates text"| node_llm
node_gateway -->|"returns reply"| node_user
node_user -->|"searches books"| node_booksearch
node_booksearch -->|"searches catalogue"| node_solrrepo
node_booksearch -->|"formats results"| node_searchresponse
node_searchresponse -->|"returns matches"| node_user

click node_gateway "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/api/RequestGateway.java"
click node_parser "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/inputparser/InputParser.java"
click node_sessionrequest "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/domain/session/SessionRequest.java"
click node_engine "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/engine/RecommendationEngine.java"
click node_retriever "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/ranker/CandidateRetriever.java"
click node_ranker "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/ranker/RankingService.java"
click node_recommendations "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/domain/session/Recommendations.java"
click node_sessioncache "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/storage/sessioncache/RedisSessionCache.java"
click node_sessionevent "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/engine/SessionUpdateEvent.java"
click node_observer "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/storage/sessioncache/RedisSessionObserver.java"
click node_profiledb "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/storage/userprofiledb/UserProfileDB.java"
click node_booksearch "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/api/BookSearchController.java"
click node_solrrepo "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/ranker/SolrAudiobookRepository.java"
click node_responsegen "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/response/ResponseGenerator.java"
click node_searchresponse "https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/api/BookSearchResponse.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_gateway,node_parser,node_sessionrequest,node_user toneBlue
class node_engine,node_retriever,node_ranker,node_recommendations toneAmber
class node_sessioncache,node_redis,node_sessionevent,node_observer,node_profiledb,node_postgres toneMint
class node_booksearch,node_solrrepo,node_solr,node_searchresponse toneRose
class node_responsegen,node_llm toneIndigo
```

## Components

### Request handling

- [Request gateway](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/api/RequestGateway.java): `src/main/java/com/gen3/recommenderagent/api/RequestGateway.java`
- [Input parser](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/inputparser/InputParser.java): `src/main/java/com/gen3/recommenderagent/inputparser/InputParser.java`
- [Parsed request](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/domain/session/SessionRequest.java): `src/main/java/com/gen3/recommenderagent/domain/session/SessionRequest.java`

### Recommendation workflow

- [Recommendation engine](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/engine/RecommendationEngine.java): `src/main/java/com/gen3/recommenderagent/engine/RecommendationEngine.java`
- [Candidate retriever](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/ranker/CandidateRetriever.java): `src/main/java/com/gen3/recommenderagent/ranker/CandidateRetriever.java`
- [Ranking service](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/ranker/RankingService.java): `src/main/java/com/gen3/recommenderagent/ranker/RankingService.java`
- [Recommendations](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/domain/session/Recommendations.java): `src/main/java/com/gen3/recommenderagent/domain/session/Recommendations.java`

### Session and profile state

- [Session cache](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/storage/sessioncache/RedisSessionCache.java): `src/main/java/com/gen3/recommenderagent/storage/sessioncache/RedisSessionCache.java`
- **Redis**
- [Session update event](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/engine/SessionUpdateEvent.java): `src/main/java/com/gen3/recommenderagent/engine/SessionUpdateEvent.java`
- [Redis session observer](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/storage/sessioncache/RedisSessionObserver.java): `src/main/java/com/gen3/recommenderagent/storage/sessioncache/RedisSessionObserver.java`
- [User profile database](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/storage/userprofiledb/UserProfileDB.java): `src/main/java/com/gen3/recommenderagent/storage/userprofiledb/UserProfileDB.java`
- **PostgreSQL**

### Audiobook catalogue

- [Book search controller](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/api/BookSearchController.java): `src/main/java/com/gen3/recommenderagent/api/BookSearchController.java`
- [Solr audiobook repository](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/ranker/SolrAudiobookRepository.java): `src/main/java/com/gen3/recommenderagent/ranker/SolrAudiobookRepository.java`
- **Apache Solr**
- [Book search response](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/api/BookSearchResponse.java): `src/main/java/com/gen3/recommenderagent/api/BookSearchResponse.java`

### Response generation

- [Response generator](https://github.com/juliu9/it-project/blob/main/src/main/java/com/gen3/recommenderagent/response/ResponseGenerator.java): `src/main/java/com/gen3/recommenderagent/response/ResponseGenerator.java`
- **AI model service**

### Other components

- **API user**

## Connections

- API user → Request gateway: submits request
- Request gateway → Input parser: parses text
- Input parser → AI model service: extracts intent
- Input parser → Parsed request: creates request
- Request gateway → Recommendation engine: processes request
- Recommendation engine → Session cache: reads session
- Session cache → Redis: reads/writes
- Recommendation engine → Candidate retriever: retrieves candidates
- Candidate retriever → Solr audiobook repository: searches catalogue
- Solr audiobook repository → Apache Solr: queries books
- Recommendation engine → Ranking service: ranks candidates
- Ranking service → Recommendations: creates results
- Recommendation engine → Session update event: publishes update
- Session update event → Redis session observer: notifies listener
- Redis session observer → Session cache: updates session
- Recommendation engine → User profile database: uses profile
- User profile database → PostgreSQL: reads/writes profile
- Request gateway → Response generator: generates reply
- Response generator → AI model service: generates text
- Request gateway → API user: returns reply
- API user → Book search controller: searches books
- Book search controller → Solr audiobook repository: searches catalogue
- Book search controller → Book search response: formats results
- Book search response → API user: returns matches