# gautamkr538/springai-bots architecture

> Architecture diagram of the GitHub repository gautamkr538/springai-bots, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gautamkr538/springai-bots
- Repository: https://github.com/gautamkr538/springai-bots

## Overview

##### Project Type and Purpose
- Type: Backend microservice (Spring Boot) with REST APIs.
- Purpose: Provide chat and weather endpoints, perform web-data crawling, extract/enrich content, compute AI embeddings (RAG), and return structured responses.

##### File Structure
- Top-level artifacts: compose.yaml (Docker Compose), pom.xml (Maven), src/main/java (code), src/main/resources/application.properties.
- Config packages: EmbeddingConfig, SwaggerConfig.
- Controllers: ChatController, WeatherController.
- DTOs: WebDataRequest, BlogPostResponseDTO, ErrorResponse.
- Services (interfaces & implementations): ChatService(+Impl), WebDataService(+Impl), WeatherServiceImpl, plus utility WebDataUtils.
- Exception handling: custom exceptions + GlobalExceptionHandler.

##### README
- Confirms multimedia features with Spring AI and web crawling.
- No explicit DB layer shown, but DatabaseException exists—reserve space for data persistence or future extension.

##### Main Components & Interactions
a. API Layer (REST Controllers)
- ChatController (POST /chat)
- WeatherController (GET/POST /weather)
- (Optionally) endpoints under WebDataService if exposed.
b. Service Layer
- ChatServiceImpl: orchestrates RAG flow—calls WebDataService, EmbeddingConfig’s vector store, OpenAI client.
- WebDataServiceImpl: performs web crawling, content extraction (WebDataUtils).
- WeatherServiceImpl & WeatherTools: calls third-party weather APIs and transforms results.
c. Config Layer
- EmbeddingConfig: sets up embedding/vector store bean.
- SwaggerConfig: configures Swagger UI for API docs.
d. Utility Layer
- WebDataUtils: low-level HTML parsing, cleaning.
e. Exception Layer
- GlobalExceptionHandler: maps exceptions (ChatServiceException, CrawlException, DatabaseException) to HTTP error responses using ErrorResponse DTO.
f. External Systems
- External websites to crawl.
- OpenAI (or other AI provider) for embeddings and chat completions.
- Third-party weather API.
- (Future) Database or vector store for persistence.

##### Architectural Patterns & Design Principles
- Layered architecture: Controller → Service → Utility/External.
- Dependency Injection for Config and Services.
- Exception translation via GlobalExceptionHandler.
- Externalized config via application.properties and Docker Compose.
- API documentation via Swagger.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Controllers Layer
    subgraph "Controllers" 
        direction TB
        ChatController["«@RestController»\nChatController\nPOST /chat"]:::controllers
        WeatherController["«@RestController»\nWeatherController\nGET/POST /weather"]:::controllers
    end

    %% Services Layer
    subgraph "Services"
        direction TB
        ChatServiceImpl["ChatServiceImpl"]:::services
        WebDataServiceImpl["WebDataServiceImpl"]:::services
        WeatherServiceImpl["WeatherServiceImpl"]:::services
        WeatherTools["WeatherTools"]:::services
    end

    %% Config & Utils Layer
    subgraph "Config & Utils"
        direction TB
        EmbeddingConfig["EmbeddingConfig"]:::config
        SwaggerConfig["SwaggerConfig"]:::config
        WebDataUtils["WebDataUtils"]:::utils
    end

    %% Exception Layer
    subgraph "Exception Handling"
        direction TB
        GlobalExceptionHandler["GlobalExceptionHandler"]:::exception
        ErrorResponse["ErrorResponse DTO"]:::dto
    end

    %% DTOs
    subgraph "DTOs"
        direction TB
        WebDataRequest["WebDataRequest DTO"]:::dto
        BlogPostResponseDTO["BlogPostResponseDTO"]:::dto
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        ExternalWeb["External Website"]:::external
        OpenAI["OpenAI API"]:::external
        WeatherAPI["Third-Party Weather API"]:::external
        DockerCompose["Docker Compose Network"]:::external
    end

    %% Flows
    %% Controllers to Services
    ChatController -->|"postChat() calls chat()"| ChatServiceImpl
    WeatherController -->|"getWeather() calls getWeather()"| WeatherServiceImpl

    %% ChatServiceImpl flows
    ChatServiceImpl -->|"fetchAndExtract(url)"| WebDataServiceImpl
    ChatServiceImpl -->|"computeEmbeddings()"| EmbeddingConfig
    ChatServiceImpl -->|"callCompletion()"| OpenAI

    %% WebDataServiceImpl flows
    WebDataServiceImpl -->|"parseHtml()"| WebDataUtils
    WebDataServiceImpl -->|"returns content"| ChatServiceImpl

    %% WeatherServiceImpl flows
    WeatherServiceImpl -->|"transformData()"| WeatherTools
    WeatherServiceImpl -->|"callAPI()"| WeatherAPI

    %% Exception flows
    ChatServiceImpl -->|"throws exceptions"| GlobalExceptionHandler
    WebDataServiceImpl -->|"throws exceptions"| GlobalExceptionHandler
    WeatherServiceImpl -->|"throws exceptions"| GlobalExceptionHandler
    GlobalExceptionHandler -->|"maps to"| ErrorResponse

    %% DTO usage
    ChatController -->|"accepts"| WebDataRequest
    ChatServiceImpl -->|"returns"| BlogPostResponseDTO
    ChatController -->|"returns"| BlogPostResponseDTO

    %% Config utils
    SwaggerConfig -->|"generates docs for"| ChatController
    SwaggerConfig -->|"generates docs for"| WeatherController
    EmbeddingConfig -->|"provides bean to"| ChatServiceImpl

    %% External network
    ChatServiceImpl -->|"network via"| DockerCompose
    WeatherServiceImpl -->|"network via"| DockerCompose

    %% External Systems connections
    WebDataServiceImpl --> ExternalWeb
    ChatServiceImpl --> OpenAI
    WeatherServiceImpl --> WeatherAPI

    %% Click Events
    click ChatController "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/controller/ChatController.java"
    click WeatherController "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/controller/WeatherController.java"
    click ChatServiceImpl "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/service/serviceImpl/ChatServiceImpl.java"
    click WebDataServiceImpl "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/service/serviceImpl/WebDataServiceImpl.java"
    click WeatherServiceImpl "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/service/serviceImpl/WeatherServiceImpl.java"
    click WeatherTools "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/service/serviceImpl/WeatherTools.java"
    click EmbeddingConfig "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/config/EmbeddingConfig.java"
    click SwaggerConfig "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/config/SwaggerConfig.java"
    click WebDataUtils "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/utils/WebDataUtils.java"
    click GlobalExceptionHandler "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/exception/GlobalExceptionHandler.java"
    click WebDataRequest "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/dto/WebDataRequest.java"
    click BlogPostResponseDTO "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/dto/BlogPostResponseDTO.java"
    click ErrorResponse "https://github.com/gautamkr538/springai-bots/blob/main/src/main/java/com/SpringAI/RAG/dto/ErrorResponse.java"

    %% Styles
    classDef controllers fill:#BDD7EE,stroke:#2E75B6,color:#000;
    classDef services fill:#C6E0B4,stroke:#389E0D,color:#000;
    classDef config fill:#FFE699,stroke:#D09B2D,color:#000;
    classDef utils fill:#FFE699,stroke:#D09B2D,color:#000;
    classDef exception fill:#F4CCCC,stroke:#CC0000,color:#000;
    classDef dto fill:#D9D2E9,stroke:#5B0FBE,color:#000;
    classDef external fill:#CCCCCC,stroke:#666666,color:#000;
```
