# lucasnscr/ai-financial-analyst architecture

> Architecture diagram of the GitHub repository lucasnscr/ai-financial-analyst, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucasnscr/ai-financial-analyst
- Repository: https://github.com/lucasnscr/ai-financial-analyst

## Overview

##### Project type and purpose
- This is a Spring Boot–based backend microservice (no UI) that implements an AI Personal Financial Analyst. It ingests real-time stock and crypto data via an external API, persists raw data in MongoDB, converts it into embeddings using an LLM, stores embeddings in PostgreSQL with PGVector, and exposes two REST endpoints: one to load/update data and one to chat/query the model.

##### Top-level architectural layers (from file tree & README)
- Presentation/API layer
– Controllers: LoadDataController, ChatController
– Secured by Keycloak JWT (SecurityConfig, JwtConverter)
- Service/Business logic layer
– DataLoadingService (orchestrates fetch → convert → store)
– ChatService (orchestrates query → RAG retrieval → LLM invoke → formatting)
- Adapter/Integration layer
– AlphaClient​* classes (classification, economy, fundamentals, market, newsAndSentimentals, technical) using WebClient
– Converters (ClassificationConverter, EconomyConverter, etc.) transform raw API DTO → domain model
– Formatters prepare text/metadata for LLM
– AIFinancialRepository orchestrates embedding generation + vector store retrieval
- Persistence layer
– MongoDB (spring-boot-starter-data-mongodb, repositories per domain model)
– PostgreSQL with PGVector (spring-ai-pgvector-store)
- AI/ML layer
– LLM models (OpenAI GPT-4o, DeepSeek R1 via spring-ai-openai & spring-ai-ollama)
– LLMContent component gathers formatted prompts & embeddings
- Infrastructure/DevOps
– Dockerfile + docker-compose.yml (local MongoDB, PGVector, Mongo-Express)
– GitHub Actions (maven.yml)
– Terraform scripts (AWS VPC, RDS, ElasticCache, Lambda, Cognito, MongoDB Atlas, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        Keycloak["Keycloak Identity Provider"]:::external
        AlphaAPI["Alpha Financial Data API"]:::external
        LLM["OpenAI/DeepSeek LLM Endpoint"]:::external
    end

    %% Spring Boot Application
    subgraph "Spring Boot Application" 
        subgraph "Presentation/API Layer"
            LoadDataController["LoadDataController"]:::app
            ChatController["ChatController"]:::app
        end
        subgraph "Security"
            SecurityConfig["SecurityConfig"]:::app
            JwtConverter["JwtConverter"]:::app
            JwtConverterProps["JwtConverterProperties"]:::app
        end
        subgraph "Configuration"
            VectorDbConfig["VectorDbConfig"]:::app
            WebClientConfig["WebClientConfig"]:::app
            CorsConfig["CorsConfig"]:::app
        end
        subgraph "Service Layer"
            DataLoadingService["DataLoadingService"]:::app
            ChatService["ChatService"]:::app
        end
        subgraph "Adapter/Integration Layer"
            subgraph "Clients"
                C1["AlphaClientClassification"]:::app
                C2["AlphaClientEconomy"]:::app
                C3["AlphaClientFundamentals"]:::app
                C4["AlphaClientMarket"]:::app
                C5["AlphaClientNewsSentimentals"]:::app
                C6["AlphaClientTechnical"]:::app
            end
            subgraph "Converters"
                CC1["ClassificationConverter"]:::app
                CC2["EconomyConverter"]:::app
                CC3["FundamentalsConverter"]:::app
                CC4["MarketConverter"]:::app
                CC5["NewsAndSentimentalsConverter"]:::app
                CC6["TechnicalConverter"]:::app
            end
            subgraph "Formatters"
                F1["ClassificationFormatter"]:::app
                F2["EconomyFormatter"]:::app
                F3["FundamentalsFormatter"]:::app
                F4["StockFormatter"]:::app
                F5["NewsFormatter"]:::app
                F6["TechnicalFormatter"]:::app
            end
            AIREPO["AIFinancialRepository"]:::app
        end
        subgraph "Persistence Layer"
            Mongo["MongoDB"]:::db
            Postgres["PostgreSQL + PGVector"]:::db
        end
        subgraph "AI/ML Layer"
            LLMContent["LLMContent"]:::app
        end
    end

    %% Infrastructure / DevOps
    subgraph "Infrastructure / DevOps"
        DockerCompose["Docker Compose"]:::infra
        Terraform["Terraform Scripts"]:::infra
        CICD["CI/CD Pipeline"]:::infra
    end

    %% Relationships
    Keycloak -->|"JWT"| LoadDataController
    Keycloak -->|"JWT"| ChatController

    LoadDataController -->|"calls"| DataLoadingService
    DataLoadingService -->|"calls"| C1
    DataLoadingService -->|"calls"| C2
    DataLoadingService -->|"calls"| C3
    DataLoadingService -->|"calls"| C4
    DataLoadingService -->|"calls"| C5
    DataLoadingService -->|"calls"| C6

    C1 -->|"HTTP JSON"| AlphaAPI
    C2 -->|"HTTP JSON"| AlphaAPI
    C3 -->|"HTTP JSON"| AlphaAPI
    C4 -->|"HTTP JSON"| AlphaAPI
    C5 -->|"HTTP JSON"| AlphaAPI
    C6 -->|"HTTP JSON"| AlphaAPI

    AlphaAPI -->|"raw JSON"| CC1
    AlphaAPI -->|"raw JSON"| CC2
    AlphaAPI -->|"raw JSON"| CC3
    AlphaAPI -->|"raw JSON"| CC4
    AlphaAPI -->|"raw JSON"| CC5
    AlphaAPI -->|"raw JSON"| CC6

    CC1 -->|"domain objects"| Mongo
    CC1 -->|"domain objects"| AIREPO
    CC2 -->|"domain objects"| Mongo
    CC2 -->|"domain objects"| AIREPO
    CC3 -->|"domain objects"| Mongo
    CC3 -->|"domain objects"| AIREPO
    CC4 -->|"domain objects"| Mongo
    CC4 -->|"domain objects"| AIREPO
    CC5 -->|"domain objects"| Mongo
    CC5 -->|"domain objects"| AIREPO
    CC6 -->|"domain objects"| Mongo
    CC6 -->|"domain objects"| AIREPO

    ChatController -->|"calls"| ChatService
    ChatService -->|"RAG retrieve"| AIREPO
    ChatService -->|"build prompt"| LLMContent
    LLMContent -->|"requests"| LLM
    LLM -->|"response"| ChatService
    ChatService -->|"response"| ChatController

    CICD --> DockerCompose
    CICD --> Terraform

    %% Click Events
    click LoadDataController "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/controller/LoadDataController.java"
    click ChatController "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/controller/ChatController.java"
    click SecurityConfig "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/security/SecurityConfig.java"
    click JwtConverter "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/security/JwtConverter.java"
    click JwtConverterProps "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/security/JwtConverterProperties.java"
    click DataLoadingService "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/service/DataLoadingService.java"
    click ChatService "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/service/ChatService.java"
    click C1 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/client/AlphaClientClassification.java"
    click C2 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/client/AlphaClientEconomy.java"
    click C3 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/client/AlphaClientFundamentals.java"
    click C4 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/client/AlphaClientMarket.java"
    click C5 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/client/AlphaClientNewsSentimentals.java"
    click C6 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/client/AlphaClientTechnical.java"
    click CC1 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/converter/ClassificationConverter.java"
    click CC2 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/converter/EconomyConverter.java"
    click CC3 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/converter/FundamentalsConverter.java"
    click CC4 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/converter/MarketConverter.java"
    click CC5 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/converter/NewsAndSentimentalsConverter.java"
    click CC6 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/converter/TechnicalConverter.java"
    click F1 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/formatter/ClassificationFormatter.java"
    click F2 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/formatter/EconomyFormatter.java"
    click F3 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/formatter/FundamentalsFormatter.java"
    click F4 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/formatter/StockFormatter.java"
    click F5 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/formatter/NewsFormatter.java"
    click F6 "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/formatter/TechnicalFormatter.java"
    click AIREPO "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/repository/AIFinancialRepository.java"
    click VectorDbConfig "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/config/VectorDbConfig.java"
    click WebClientConfig "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/config/WebClientConfig.java"
    click CorsConfig "https://github.com/lucasnscr/ai-financial-analyst/blob/main/src/main/java/com/lucasnscr/ai_financial_analyst/config/CorsConfig.java"

    %% Styles
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef app fill:#E0F7FA,stroke:#333,stroke-width:1px
    classDef db fill:#E8F5E9,stroke:#333,stroke-width:1px
    classDef infra fill:#FFE0B2,stroke:#333,stroke-width:1px
```
