# janardhanpalanisamy/ai-room-recommendation-system architecture

> Architecture diagram of the GitHub repository janardhanpalanisamy/ai-room-recommendation-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/janardhanpalanisamy/ai-room-recommendation-system
- Repository: https://github.com/janardhanpalanisamy/ai-room-recommendation-system

## Overview

This is a FastAPI room-recommendation backend with two principal workflows: ingesting room content into a vector-backed knowledge base, and answering a natural-language room query using similarity retrieval and an LLM response. The app mounts the room API; its router delegates to a controller, which delegates business work to the service. The service coordinates semantic chunking, embeddings, repository persistence or search, and response generation. The README documents pgvector and Bedrock capabilities. Some implementation files, including migrations and error mapping, were not excerpted; their relationships are shown only where the app excerpt or README supports them.

Main entry points: [`src/app.py`](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/app.py) (FastAPI app), [`src/services/room_service.py`](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/services/room_service.py) (Recommendation service), [`src/routers/room_router.py`](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/routers/room_router.py) (Room routes), [`src/controllers/room_controller.py`](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/controllers/room_controller.py) (Room controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API handling"]
  node_app["FastAPI app<br/>[app.py]"]
  node_router["Room routes<br/>[room_router.py]"]
  node_controller["Room controller<br/>[room_controller.py]"]
  node_requestdto["Request DTOs<br/>[room_dto.py]"]
  node_responses["API responses"]
  node_exceptions["App exceptions"]
  node_errors["Error codes<br/>[error_codes.py]"]
  node_error_mappers["Error mapping<br/>[error_mappers.py]"]
end

subgraph group_ai["Recommendation AI"]
  node_service["Recommendation service<br/>[room_service.py]"]
  node_chunking["Semantic chunking<br/>[llm_utility.py]"]
  node_embeddings["Bedrock embeddings<br/>[bedrock.py]"]
  node_prompt_llm["Prompt and LLM<br/>[llm_utility.py]"]
end

subgraph group_data["Knowledge base data"]
  node_repository["Knowledge repository<br/>[room_repository.py]"]
  node_room_model["Room vector model<br/>[room_model.py]"]
  node_database["Database sessions<br/>[database.py]"]
end

subgraph group_platform["Runtime support"]
  node_config["Runtime configuration<br/>[config_manager.py]"]
  node_http_status["HTTP status codes<br/>[http_status.py]"]
  node_migration["Startup migration"]
end

node_client(("API caller"))
node_bedrock{{"AWS Bedrock"}}
node_postgres[("PostgreSQL pgvector")]

node_client -->|"sends request"| node_app
node_app -->|"mounts routes"| node_router
node_router -->|"validates input"| node_requestdto
node_router -->|"dispatches"| node_controller
node_controller -->|"delegates"| node_service
node_router -->|"serializes response"| node_responses
node_controller -->|"creates response"| node_responses
node_controller -->|"raises on failure"| node_exceptions
node_app -->|"handles exceptions"| node_exceptions
node_app -->|"formats validation errors"| node_responses
node_app -->|"uses error codes"| node_errors
node_app -->|"sets status"| node_http_status
node_app -->|"runs at startup"| node_migration
node_service -->|"chunks content"| node_chunking
node_service -->|"creates embeddings"| node_embeddings
node_service -->|"stores or searches"| node_repository
node_service -->|"builds response"| node_prompt_llm
node_chunking -->|"uses embed model"| node_embeddings
node_embeddings -->|"invokes model"| node_bedrock
node_prompt_llm -->|"invokes model"| node_bedrock
node_repository -->|"opens sessions"| node_database
node_repository -->|"creates records"| node_room_model
node_repository -->|"writes and searches vectors"| node_postgres
node_database -->|"loads settings"| node_config
node_database -.->|"connects to store"| node_postgres
node_embeddings -->|"reads model settings"| node_config
node_prompt_llm -->|"reads model settings"| node_config
node_error_mappers -->|"formats errors"| node_responses
node_error_mappers -->|"maps codes"| node_errors

click node_app "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/app.py"
click node_router "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/routers/room_router.py"
click node_controller "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/controllers/room_controller.py"
click node_requestdto "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/dtos/room_dto.py"
click node_responses "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/dtos/api_response_dto.py"
click node_exceptions "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/dtos/custom_app_exception.py"
click node_errors "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/errors/error_codes.py"
click node_error_mappers "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/errors/error_mappers.py"
click node_service "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/services/room_service.py"
click node_chunking "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/utilities/llm_utility.py"
click node_embeddings "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/utilities/bedrock.py"
click node_prompt_llm "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/utilities/llm_utility.py"
click node_repository "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/repositories/room_repository.py"
click node_room_model "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/models/room_model.py"
click node_database "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/database/database.py"
click node_config "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/config/config_manager.py"
click node_http_status "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/constants/http_status.py"
click node_migration "https://github.com/janardhanpalanisamy/ai-room-recommendation-system/tree/main/src/migrations"

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_app,node_router,node_controller,node_requestdto,node_responses,node_exceptions,node_errors,node_error_mappers toneBlue
class node_service,node_chunking,node_embeddings,node_prompt_llm,node_postgres toneAmber
class node_repository,node_room_model,node_database,node_client toneMint
class node_config,node_http_status,node_migration toneRose
class node_bedrock toneIndigo
```

## Components

### API handling

- [FastAPI app](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/app.py): `src/app.py`
- [Room routes](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/routers/room_router.py): `src/routers/room_router.py`
- [Room controller](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/controllers/room_controller.py): `src/controllers/room_controller.py`
- [Request DTOs](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/dtos/room_dto.py): `src/dtos/room_dto.py`
- [API responses](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/dtos/api_response_dto.py): `src/dtos/api_response_dto.py`
- [App exceptions](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/dtos/custom_app_exception.py): `src/dtos/custom_app_exception.py`
- [Error codes](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/errors/error_codes.py): `src/errors/error_codes.py`
- [Error mapping](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/errors/error_mappers.py): `src/errors/error_mappers.py`

### Recommendation AI

- [Recommendation service](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/services/room_service.py): `src/services/room_service.py`
- [Semantic chunking](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/utilities/llm_utility.py): `src/utilities/llm_utility.py`
- [Bedrock embeddings](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/utilities/bedrock.py): `src/utilities/bedrock.py`
- [Prompt and LLM](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/utilities/llm_utility.py): `src/utilities/llm_utility.py`

### Knowledge base data

- [Knowledge repository](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/repositories/room_repository.py): `src/repositories/room_repository.py`
- [Room vector model](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/models/room_model.py): `src/models/room_model.py`
- [Database sessions](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/database/database.py): `src/database/database.py`

### Runtime support

- [Runtime configuration](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/config/config_manager.py): `src/config/config_manager.py`
- [HTTP status codes](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/blob/main/src/constants/http_status.py): `src/constants/http_status.py`
- [Startup migration](https://github.com/janardhanpalanisamy/ai-room-recommendation-system/tree/main/src/migrations): `src/migrations`

### Other components

- **API caller**
- **AWS Bedrock**
- **PostgreSQL pgvector**

## Connections

- API caller → FastAPI app: sends request (evidence: `README.md`)
- FastAPI app → Room routes: mounts routes (evidence: `src/app.py`)
- Room routes → Request DTOs: validates input (evidence: `src/routers/room_router.py`)
- Room routes → Room controller: dispatches (evidence: `src/routers/room_router.py`)
- Room controller → Recommendation service: delegates (evidence: `src/controllers/room_controller.py`)
- Room routes → API responses: serializes response (evidence: `src/routers/room_router.py`)
- Room controller → API responses: creates response (evidence: `src/controllers/room_controller.py`)
- Room controller → App exceptions: raises on failure (evidence: `src/controllers/room_controller.py`)
- FastAPI app → App exceptions: handles exceptions (evidence: `src/app.py`)
- FastAPI app → API responses: formats validation errors (evidence: `src/app.py`)
- FastAPI app → Error codes: uses error codes (evidence: `src/app.py`)
- FastAPI app → HTTP status codes: sets status (evidence: `src/app.py`)
- FastAPI app → Startup migration: runs at startup (evidence: `src/app.py`)
- Recommendation service → Semantic chunking: chunks content (evidence: `src/services/room_service.py`)
- Recommendation service → Bedrock embeddings: creates embeddings (evidence: `src/services/room_service.py`)
- Recommendation service → Knowledge repository: stores or searches (evidence: `src/services/room_service.py`)
- Recommendation service → Prompt and LLM: builds response (evidence: `src/services/room_service.py`)
- Semantic chunking → Bedrock embeddings: uses embed model (evidence: `src/utilities/llm_utility.py`)
- Bedrock embeddings → AWS Bedrock: invokes model (evidence: `src/utilities/bedrock.py`)
- Prompt and LLM → AWS Bedrock: invokes model (evidence: `src/utilities/llm_utility.py`)
- Knowledge repository → Database sessions: opens sessions (evidence: `src/repositories/room_repository.py`)
- Knowledge repository → Room vector model: creates records (evidence: `src/repositories/room_repository.py`)
- Knowledge repository → PostgreSQL pgvector: writes and searches vectors (evidence: `README.md`)
- Database sessions → Runtime configuration: loads settings (evidence: `src/database/database.py`)
- Database sessions → PostgreSQL pgvector: connects to store
- Bedrock embeddings → Runtime configuration: reads model settings (evidence: `src/utilities/bedrock.py`)
- Prompt and LLM → Runtime configuration: reads model settings (evidence: `src/utilities/llm_utility.py`)
- Error mapping → API responses: formats errors (evidence: `src/errors/error_mappers.py`)
- Error mapping → Error codes: maps codes (evidence: `src/errors/error_mappers.py`)
