# ibomoko/openai-embedding architecture

> Architecture diagram of the GitHub repository ibomoko/openai-embedding, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibomoko/openai-embedding
- Repository: https://github.com/ibomoko/openai-embedding

## Overview

##### Main Components
- API Gateway / Controller Layer: Represent the HTTP endpoints (e.g., POST /v1/api/topic, GET /v1/api/topic/{id}/detect-anomaly) implemented in the TopicController. This component handles incoming REST API calls.
- Service Layer: Represent the business logic handled in services such as TopicService and its implementation (TopicServiceImpl). This layer processes the logic for topic creation, anomaly detection, and orchestrates calls to other layers.
- Data Access Layer (DAO/Repository): Represent the repository classes (e.g., TopicRepository, TopicPostRepository, PostSimilarityRepository) that manage interactions with the database.
- Domain/Entity Layer: Represent the entities (Topic, TopicPost, PostSimilarity) that model the core business data.
- External Systems and Integrations:
- OpenAI Embedding Model: Even if the integration is abstracted, indicate that the service interacts (directly or indirectly) with the OpenAI embedding API for processing text.
- Database: Represent a PostgreSQL database which uses pgvector for vector operations. Also include Liquibase as the mechanism for DB schema migration (changelog files).
- Cross-Cutting Concerns: Include a component for Global Exception Handling and error management (GlobalExceptionHandler, ErrorResponse, exception classes).

##### Relationships and Interactions
- Service Layer interacting with the Data Access Layer to persist and query topic, post, and embedding data.
- Integration between the Service Layer (or a dedicated integration component if present) and the external OpenAI Embedded API.
- Directional flows from Liquibase (or the DB migration process) to the Database to reflect schema management.
- Present error handling paths (e.g., error responses flowing back from the Global Exception Handler to the Controller).

##### Architectural Patterns and Design Principles
- Layered Architecture: Clearly separate the controller (API), service (business logic), DAO (data persistence), and domain layers.
- Reactive Programming with Spring WebFlux: Note that endpoints are designed to be non-blocking and reactive, affecting how data flows through the system.
- API Documentation with Swagger/OpenAPI: Indicate that the API layer is documented, which is useful for client-side integrations.
- Database Migration with Liquibase: Highlight that the project manages schema changes and versioning through Liquibase changelogs.
- Clear error handling: The presence of a global exception handler improves robustness.

##### Relevant Technologies and Frameworks
- Java (Spring Boot, Spring WebFlux)
- Gradle (for build management)
- OpenAPI/Swagger for API documentation
- Liquibase for DB migrations
- pgvector extension for PostgreSQL
- Possibly integration with OpenAI’s API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        TC["TopicController"]:::api
        SC["SwaggerConfig"]:::api
        GE["GlobalExceptionHandler"]:::error
        ER["ErrorResponse"]:::error
    end

    %% Service Layer
    subgraph "Service Layer"
        TS["TopicService (Interface)"]:::service
        TSI["TopicServiceImpl"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        TR["TopicRepository"]:::dao
        TPR["TopicPostRepository"]:::dao
        PSR["PostSimilarityRepository"]:::dao
    end

    %% Domain/Entity Layer
    subgraph "Domain Layer"
        TE["Topic Entity"]:::domain
        TPE["TopicPost Entity"]:::domain
        PSE["PostSimilarity Entity"]:::domain
    end

    %% DB Migration and Database
    subgraph "DB Migration & Database"
        LMC["Liquibase Master Changelog"]:::liquibase
        LV1T["Liquibase v1 Changelog Tables"]:::liquibase
        LV1["Liquibase v1 Changelog"]:::liquibase
        DB["PostgreSQL with pgvector"]:::database
    end

    %% External Integration
    subgraph "External Integration"
        OAA["OpenAIEmbeddingApplication"]:::external
        OAC["OpenAIConstants"]:::external
    end

    %% Interactions
    %% API Layer to Service Layer
    TC -->|"calls"| TSI
    %% Service Layer interaction
    TSI -->|"uses"| TR
    TSI -->|"uses"| TPR
    TSI -->|"uses"| PSR
    %% Service Layer integration with External OpenAI API
    TSI -->|"integrates"| OAA
    %% DAO to Domain association
    TR -->|"mapsTo"| TE
    TPR -->|"mapsTo"| TPE
    PSR -->|"mapsTo"| PSE

    %% DB Migration to Database
    LMC --> DB
    LV1T --> DB
    LV1 --> DB
    %% Repositories accessing Database
    TR --- DB
    TPR --- DB
    PSR --- DB

    %% Global Exception Handling flow back to API Controller
    GE -->|"errorsTo"| TC

    %% Swagger documentation is part of API
    SC --- TC

    %% Class Definitions for colors
    classDef api fill:#C6E5FF,stroke:#036,stroke-width:2px;
    classDef service fill:#FFE5B4,stroke:#C55,stroke-width:2px;
    classDef dao fill:#E0FFC6,stroke:#393,stroke-width:2px;
    classDef domain fill:#FFF2CC,stroke:#AA3,stroke-width:2px;
    classDef liquibase fill:#F9D9F9,stroke:#D16,stroke-width:2px;
    classDef database fill:#FFD6D6,stroke:#D00,stroke-width:2px;
    classDef external fill:#DFD,stroke:#484,stroke-width:2px;
    classDef error fill:#FFCCCC,stroke:#C00,stroke-width:2px;

    %% Click Events
    click TC "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/controller/TopicController.java"
    click SC "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/config/SwaggerConfig.java"
    click GE "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/error/GlobalExceptionHandler.java"
    click ER "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/error/ErrorResponse.java"
    click TS "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/service/TopicService.java"
    click TSI "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/service/impl/TopicServiceImpl.java"
    click TR "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/dao/TopicRepository.java"
    click TPR "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/dao/TopicPostRepository.java"
    click PSR "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/dao/PostSimilarityRepository.java"
    click TE "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/entity/Topic.java"
    click TPE "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/entity/TopicPost.java"
    click PSE "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/entity/PostSimilarity.java"
    click LMC "https://github.com/ibomoko/openai-embedding/blob/main/src/main/resources/db/changelog/changelog-master.xml"
    click LV1T "https://github.com/ibomoko/openai-embedding/blob/main/src/main/resources/db/changelog/v1/changelog-v1.0-tables.xml"
    click LV1 "https://github.com/ibomoko/openai-embedding/blob/main/src/main/resources/db/changelog/v1/changelog-v1.0.xml"
    click OAA "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/OpenAIEmbeddingApplication.java"
    click OAC "https://github.com/ibomoko/openai-embedding/blob/main/src/main/java/com/ai/openaiembedding/constants/OpenAIConstants.java"
```
