# astik2004/bankwise-ai-project architecture

> Architecture diagram of the GitHub repository astik2004/bankwise-ai-project, 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/astik2004/bankwise-ai-project
- Repository: https://github.com/astik2004/bankwise-ai-project

## Overview

BankWise is a banking-question assistant whose main journey is secure sign-in, document-backed knowledge-base preparation, then a user-scoped chat request answered through RAG and saved as conversation history. The graph separates document ingestion, knowledge-base/vector work, RAG stages, and chat/conversation persistence, with authentication as a supporting capability. The README documents the overall flows; source excerpts show document ingestion, embedding, and LLM invocation. Several subsystem implementations, including chat persistence and retrieval, were not sampled, so those connections are documented relationships rather than inspected calls.

Main entry points: [`src/main/java/com/bankwise/rag/service/RagServiceImpl.java`](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/service/RagServiceImpl.java) (RAG orchestration), [`src/main/java/com/bankwise/document/ingestion/DocumentIngestionServiceImpl.java`](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/ingestion/DocumentIngestionServiceImpl.java) (Document ingestion), [`src/main/java/com/bankwise/chat/service/ChatServiceImpl.java`](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/chat/service/ChatServiceImpl.java) (Chat service), [`src/main/java/com/bankwise/auth/service/AuthServiceImpl.java`](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/auth/service/AuthServiceImpl.java) (Authentication service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Identity and security"]
  node_auth_api["Auth API"]
  node_auth_service["Authentication service"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_principal["Security principal"]
  node_user_store[("User records<br/>[User.java]")]
end

subgraph group_docs["Document ingestion"]
  node_document_api["Document API"]
  node_document_service["Document service"]
  node_ingestion["Document ingestion"]
  node_storage["Document storage"]
  node_document_record[("Document records<br/>[Document.java]")]
end

subgraph group_knowledge["Knowledge base"]
  node_kb_service["Knowledge-base service"]
  node_kb_ingestion["Knowledge-base ingestion"]
  node_chunks[("Knowledge-base chunks")]
  node_embedding["Embedding service"]
  node_vector_store[("Vector store")]
end

subgraph group_rag["RAG answer pipeline"]
  node_rag_service["RAG orchestration"]
  node_query_processor["Query processor"]
  node_retriever["Document retriever"]
  node_context_builder["Context builder"]
  node_prompt_builder["Prompt builder"]
  node_llm["LLM service"]
  node_validator["Answer validator"]
  node_citation_builder["Citation builder"]
end

subgraph group_chat["Chat and history"]
  node_chat_api["Chat API"]
  node_chat_service["Chat service"]
  node_conversation_service["Conversation service"]
  node_conversation_store[("Conversation records<br/>[Conversation.java]")]
  node_message_store[("Chat messages<br/>[ChatMessage.java]")]
end

node_user(("User"))
node_llm_provider{{"Chat model provider"}}

node_user -->|"registers or logs in"| node_auth_api
node_auth_api -->|"delegates auth"| node_auth_service
node_auth_service -->|"reads and writes"| node_user_store
node_auth_service -->|"issues tokens"| node_jwt
node_user -->|"uploads documents"| node_document_api
node_document_api -->|"delegates upload"| node_document_service
node_document_service -.->|"manages records"| node_document_record
node_document_service -.->|"starts ingestion"| node_ingestion
node_ingestion -->|"loads document"| node_document_record
node_ingestion -->|"reads file"| node_storage
node_user -->|"manages knowledge base"| node_kb_service
node_ingestion -.->|"provides chunks"| node_kb_ingestion
node_kb_ingestion -.->|"creates chunks"| node_chunks
node_kb_ingestion -.->|"requests embeddings"| node_embedding
node_embedding -->|"stores vectors"| node_vector_store
node_user -->|"asks question"| node_chat_api
node_chat_api -->|"delegates chat"| node_chat_service
node_chat_service -->|"requests answer"| node_rag_service
node_rag_service -->|"validates access"| node_kb_service
node_rag_service -->|"normalizes query"| node_query_processor
node_rag_service -->|"retrieves sources"| node_retriever
node_retriever -->|"searches vectors"| node_vector_store
node_rag_service -->|"builds context"| node_context_builder
node_rag_service -->|"builds prompt"| node_prompt_builder
node_rag_service -->|"generates answer"| node_llm
node_llm -->|"calls model"| node_llm_provider
node_rag_service -->|"validates answer"| node_validator
node_rag_service -->|"builds citations"| node_citation_builder
node_chat_service -->|"creates or loads thread"| node_conversation_service
node_chat_service -->|"persists messages"| node_message_store
node_conversation_service -->|"updates metadata"| node_conversation_store
node_conversation_service -.->|"tracks message count"| node_message_store

click node_auth_api "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/auth/controller/AuthController.java"
click node_auth_service "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/auth/service/AuthServiceImpl.java"
click node_jwt "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/security/jwt/JwtService.java"
click node_principal "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/security/principal/CustomUserPrincipal.java"
click node_user_store "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/auth/domain/User.java"
click node_document_api "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/controller/DocumentController.java"
click node_document_service "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/service/DocumentService.java"
click node_ingestion "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/ingestion/DocumentIngestionServiceImpl.java"
click node_storage "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/ingestion/storage/LocalDocumentStorage.java"
click node_document_record "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/domain/Document.java"
click node_kb_service "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/knowledgebase/service/KnowledgeBaseService.java"
click node_kb_ingestion "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/knowledgebase/ingestion/KnowledgeBaseIngestionImpl.java"
click node_chunks "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/knowledgebase/domain/KnowledgeBaseChunk.java"
click node_embedding "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/knowledgebase/embedding/SpringAiEmbeddingService.java"
click node_chat_api "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/chat/controller/ChatController.java"
click node_chat_service "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/chat/service/ChatServiceImpl.java"
click node_conversation_service "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/conversation/service/ConversationServiceImpl.java"
click node_conversation_store "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/conversation/domain/Conversation.java"
click node_message_store "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/chat/domain/ChatMessage.java"
click node_rag_service "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/service/RagServiceImpl.java"
click node_query_processor "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/query/DefaultQueryProcessor.java"
click node_retriever "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/retrieval/VectorStoreDocumentRetriever.java"
click node_context_builder "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/context/DefaultContextBuilder.java"
click node_prompt_builder "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/prompt/DefaultPromptBuilder.java"
click node_llm "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/llm/SpringAiLlmService.java"
click node_validator "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/validation/DefaultAnswerValidator.java"
click node_citation_builder "https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/citation/DefaultCitationBuilder.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_auth_api,node_auth_service,node_jwt,node_principal,node_user_store,node_user toneBlue
class node_document_api,node_document_service,node_ingestion,node_storage,node_document_record toneAmber
class node_kb_service,node_kb_ingestion,node_chunks,node_embedding,node_vector_store toneMint
class node_rag_service,node_query_processor,node_retriever,node_context_builder,node_prompt_builder,node_llm,node_validator,node_citation_builder toneRose
class node_chat_api,node_chat_service,node_conversation_service,node_conversation_store,node_message_store,node_llm_provider toneIndigo
```

## Components

### Identity and security

- [Auth API](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/auth/controller/AuthController.java): `src/main/java/com/bankwise/auth/controller/AuthController.java`
- [Authentication service](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/auth/service/AuthServiceImpl.java): `src/main/java/com/bankwise/auth/service/AuthServiceImpl.java`
- [JWT service](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/security/jwt/JwtService.java): `src/main/java/com/bankwise/security/jwt/JwtService.java`
- [Security principal](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/security/principal/CustomUserPrincipal.java): `src/main/java/com/bankwise/security/principal/CustomUserPrincipal.java`
- [User records](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/auth/domain/User.java): `src/main/java/com/bankwise/auth/domain/User.java`

### Document ingestion

- [Document API](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/controller/DocumentController.java): `src/main/java/com/bankwise/document/controller/DocumentController.java`
- [Document service](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/service/DocumentService.java): `src/main/java/com/bankwise/document/service/DocumentService.java`
- [Document ingestion](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/ingestion/DocumentIngestionServiceImpl.java): `src/main/java/com/bankwise/document/ingestion/DocumentIngestionServiceImpl.java`
- [Document storage](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/ingestion/storage/LocalDocumentStorage.java): `src/main/java/com/bankwise/document/ingestion/storage/LocalDocumentStorage.java`
- [Document records](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/document/domain/Document.java): `src/main/java/com/bankwise/document/domain/Document.java`

### Knowledge base

- [Knowledge-base service](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/knowledgebase/service/KnowledgeBaseService.java): `src/main/java/com/bankwise/knowledgebase/service/KnowledgeBaseService.java`
- [Knowledge-base ingestion](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/knowledgebase/ingestion/KnowledgeBaseIngestionImpl.java): `src/main/java/com/bankwise/knowledgebase/ingestion/KnowledgeBaseIngestionImpl.java`
- [Knowledge-base chunks](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/knowledgebase/domain/KnowledgeBaseChunk.java): `src/main/java/com/bankwise/knowledgebase/domain/KnowledgeBaseChunk.java`
- [Embedding service](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/knowledgebase/embedding/SpringAiEmbeddingService.java): `src/main/java/com/bankwise/knowledgebase/embedding/SpringAiEmbeddingService.java`
- **Vector store**

### RAG answer pipeline

- [RAG orchestration](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/service/RagServiceImpl.java): `src/main/java/com/bankwise/rag/service/RagServiceImpl.java`
- [Query processor](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/query/DefaultQueryProcessor.java): `src/main/java/com/bankwise/rag/query/DefaultQueryProcessor.java`
- [Document retriever](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/retrieval/VectorStoreDocumentRetriever.java): `src/main/java/com/bankwise/rag/retrieval/VectorStoreDocumentRetriever.java`
- [Context builder](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/context/DefaultContextBuilder.java): `src/main/java/com/bankwise/rag/context/DefaultContextBuilder.java`
- [Prompt builder](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/prompt/DefaultPromptBuilder.java): `src/main/java/com/bankwise/rag/prompt/DefaultPromptBuilder.java`
- [LLM service](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/llm/SpringAiLlmService.java): `src/main/java/com/bankwise/rag/llm/SpringAiLlmService.java`
- [Answer validator](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/validation/DefaultAnswerValidator.java): `src/main/java/com/bankwise/rag/validation/DefaultAnswerValidator.java`
- [Citation builder](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/rag/citation/DefaultCitationBuilder.java): `src/main/java/com/bankwise/rag/citation/DefaultCitationBuilder.java`

### Chat and history

- [Chat API](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/chat/controller/ChatController.java): `src/main/java/com/bankwise/chat/controller/ChatController.java`
- [Chat service](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/chat/service/ChatServiceImpl.java): `src/main/java/com/bankwise/chat/service/ChatServiceImpl.java`
- [Conversation service](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/conversation/service/ConversationServiceImpl.java): `src/main/java/com/bankwise/conversation/service/ConversationServiceImpl.java`
- [Conversation records](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/conversation/domain/Conversation.java): `src/main/java/com/bankwise/conversation/domain/Conversation.java`
- [Chat messages](https://github.com/astik2004/bankwise-ai-project/blob/master/src/main/java/com/bankwise/chat/domain/ChatMessage.java): `src/main/java/com/bankwise/chat/domain/ChatMessage.java`

### Other components

- **User**
- **Chat model provider**

## Connections

- User → Auth API: registers or logs in
- Auth API → Authentication service: delegates auth (evidence: `src/main/java/com/bankwise/auth/controller/AuthController.java`)
- Authentication service → User records: reads and writes (evidence: `src/main/java/com/bankwise/auth/service/AuthServiceImpl.java`)
- Authentication service → JWT service: issues tokens (evidence: `src/main/java/com/bankwise/auth/service/AuthServiceImpl.java`)
- User → Document API: uploads documents
- Document API → Document service: delegates upload (evidence: `src/main/java/com/bankwise/document/controller/DocumentController.java`)
- Document service → Document records: manages records
- Document service → Document ingestion: starts ingestion
- Document ingestion → Document records: loads document (evidence: `src/main/java/com/bankwise/document/ingestion/DocumentIngestionServiceImpl.java`)
- Document ingestion → Document storage: reads file (evidence: `src/main/java/com/bankwise/document/ingestion/DocumentIngestionServiceImpl.java`)
- User → Knowledge-base service: manages knowledge base
- Document ingestion → Knowledge-base ingestion: provides chunks
- Knowledge-base ingestion → Knowledge-base chunks: creates chunks (evidence: `src/main/java/com/bankwise/knowledgebase/ingestion/KnowledgeBaseIngestionImpl.java`)
- Knowledge-base ingestion → Embedding service: requests embeddings
- Embedding service → Vector store: stores vectors (evidence: `src/main/java/com/bankwise/knowledgebase/embedding/SpringAiEmbeddingService.java`)
- User → Chat API: asks question
- Chat API → Chat service: delegates chat (evidence: `src/main/java/com/bankwise/chat/controller/ChatController.java`)
- Chat service → RAG orchestration: requests answer
- RAG orchestration → Knowledge-base service: validates access (evidence: `src/main/java/com/bankwise/rag/service/RagServiceImpl.java`)
- RAG orchestration → Query processor: normalizes query (evidence: `src/main/java/com/bankwise/rag/service/RagServiceImpl.java`)
- RAG orchestration → Document retriever: retrieves sources (evidence: `src/main/java/com/bankwise/rag/service/RagServiceImpl.java`)
- Document retriever → Vector store: searches vectors
- RAG orchestration → Context builder: builds context (evidence: `src/main/java/com/bankwise/rag/service/RagServiceImpl.java`)
- RAG orchestration → Prompt builder: builds prompt (evidence: `src/main/java/com/bankwise/rag/service/RagServiceImpl.java`)
- RAG orchestration → LLM service: generates answer (evidence: `src/main/java/com/bankwise/rag/service/RagServiceImpl.java`)
- LLM service → Chat model provider: calls model
- RAG orchestration → Answer validator: validates answer (evidence: `src/main/java/com/bankwise/rag/service/RagServiceImpl.java`)
- RAG orchestration → Citation builder: builds citations (evidence: `src/main/java/com/bankwise/rag/service/RagServiceImpl.java`)
- Chat service → Conversation service: creates or loads thread
- Chat service → Chat messages: persists messages
- Conversation service → Conversation records: updates metadata
- Conversation service → Chat messages: tracks message count
