# aliens983/campusbrain architecture

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

- Interactive diagram: https://gitdiagram.com/aliens983/campusbrain
- Repository: https://github.com/aliens983/campusbrain

## Overview

CampusBrain is a unified campus platform combining CAS appointments and a knowledge-base assistant. A user asks a question through the KB workflow: context-aware conversation and hybrid retrieval feed answer generation, which can call CAS for live appointment data; proposed bookings remain drafts until explicitly confirmed. The CAS branch covers campus-scoped service discovery, resource booking, review, chat, and notifications. The README documents these product capabilities and cross-service links; sampled source shows the QA orchestration and assistant-service contract, but not every controller, persistence adapter, or integration implementation.

Main entry points: [`backend/kb-service/src/main/java/com/kb/domain/rag/SearchService.java`](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/domain/rag/SearchService.java) (Hybrid retrieval), [`backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/BookServiceImpl.java`](https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/BookServiceImpl.java) (Booking lifecycle), [`backend/kb-service/src/main/java/com/kb/application/service/DocumentApplicationService.java`](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/application/service/DocumentApplicationService.java) (Document ingestion), [`backend/kb-service/src/main/java/com/kb/application/service/QaApplicationService.java`](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/application/service/QaApplicationService.java) (QA orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_webapp["Vue application<br/>[App.vue]"]
end

subgraph group_knowledge["Knowledge assistant"]
  node_qa_api["QA endpoint<br/>[QaController.java]"]
  node_qa_service["QA orchestration"]
  node_conversation["Conversation state<br/>[Conversation.java]"]
  node_answer_pipeline["Answer pipeline"]
  node_search["Hybrid retrieval<br/>[SearchService.java]"]
  node_embedding["Embedding provider"]
  node_llm["LLM and tools"]
  node_document_service["Document ingestion"]
  node_es_index[("Search index")]
  node_qdrant[("Vector store")]
  node_appointment_tool["Appointment tool"]
  node_cache[("Answer caches")]
end

subgraph group_appointments["Campus appointments"]
  node_appointment_api["CAS assistant API"]
  node_assistant_service["Appointment assistant"]
  node_booking["Booking lifecycle"]
  node_catalog["Campus service catalog"]
  node_chat["Consultation chat"]
  node_rabbit["Appointment events"]
end

subgraph group_platform["Identity and services"]
  node_gateway{{"API gateway"}}
  node_auth["Account and RBAC<br/>[AuthService.java]"]
  node_email["Email service<br/>[EmailService.java]"]
end

node_user(("Campus user"))

node_user -->|"uses"| node_webapp
node_webapp -->|"calls APIs"| node_gateway
node_gateway -.->|"routes requests"| node_qa_api
node_qa_api -.->|"delegates"| node_qa_service
node_qa_service -->|"maintains context"| node_conversation
node_qa_service -->|"retrieves and generates"| node_answer_pipeline
node_answer_pipeline -.->|"retrieves"| node_search
node_search -.->|"keyword search"| node_es_index
node_search -.->|"vector search"| node_qdrant
node_search -.->|"embeds queries"| node_embedding
node_answer_pipeline -.->|"generates answers"| node_llm
node_document_service -.->|"embeds chunks"| node_embedding
node_document_service -.->|"indexes documents"| node_es_index
node_document_service -.->|"stores vectors"| node_qdrant
node_llm -->|"calls tools"| node_appointment_tool
node_appointment_tool -->|"queries CAS"| node_appointment_api
node_appointment_api -.->|"delegates"| node_assistant_service
node_assistant_service -->|"confirms drafts"| node_booking
node_assistant_service -->|"queries services"| node_catalog
node_user -->|"books services"| node_booking
node_booking -->|"publishes changes"| node_rabbit
node_rabbit -->|"invalidates caches"| node_cache
node_user -->|"messages teacher"| node_chat
node_user -->|"authenticates"| node_auth
node_booking -->|"sends review notices"| node_email

click node_webapp "https://github.com/aliens983/campusbrain/blob/main/frontend/src/App.vue"
click node_gateway "https://github.com/aliens983/campusbrain/blob/main/backend/gateway/src/main/java/com/laoliu/gateway/GatewayApplication.java"
click node_qa_api "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/interfaces/rest/QaController.java"
click node_qa_service "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/application/service/QaApplicationService.java"
click node_conversation "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/domain/conversation/Conversation.java"
click node_answer_pipeline "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/application/service/AnswerPipeline.java"
click node_search "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/domain/rag/SearchService.java"
click node_embedding "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/infrastructure/rag/embedding/OpenAiEmbeddingService.java"
click node_llm "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/infrastructure/rag/llm/LangChain4jLlmService.java"
click node_document_service "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/application/service/DocumentApplicationService.java"
click node_es_index "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/infrastructure/persistence/elasticsearch/EsIndexService.java"
click node_qdrant "https://github.com/aliens983/campusbrain/tree/main/backend/kb-service/src/main/java/com/kb/infrastructure/persistence/qdrant"
click node_appointment_tool "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/infrastructure/rag/tool/AppointmentTool.java"
click node_appointment_api "https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/interfaces/controller/assistant/AppointmentAssistantController.java"
click node_assistant_service "https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/AppointmentAssistantService.java"
click node_booking "https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/BookServiceImpl.java"
click node_catalog "https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/ServiceItemServiceImpl.java"
click node_chat "https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/ConsultChatServiceImpl.java"
click node_auth "https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-system/src/main/java/com/laoliu/cas/system/application/service/AuthService.java"
click node_cache "https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/infrastructure/cache/SemanticCacheService.java"
click node_rabbit "https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/infrastructure/mq/BookingEventPublisher.java"
click node_email "https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-infra-api/src/main/java/com/laoliu/cas/infra/api/email/EmailService.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_webapp,node_user toneBlue
class node_qa_api,node_qa_service,node_conversation,node_answer_pipeline,node_search,node_embedding,node_llm,node_document_service,node_es_index,node_qdrant,node_appointment_tool,node_cache toneAmber
class node_appointment_api,node_assistant_service,node_booking,node_catalog,node_chat,node_rabbit toneMint
class node_gateway,node_auth,node_email toneRose
```

## Components

### Web experience

- [Vue application](https://github.com/aliens983/campusbrain/blob/main/frontend/src/App.vue): `frontend/src/App.vue`

### Knowledge assistant

- [QA endpoint](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/interfaces/rest/QaController.java): `backend/kb-service/src/main/java/com/kb/interfaces/rest/QaController.java`
- [QA orchestration](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/application/service/QaApplicationService.java): `backend/kb-service/src/main/java/com/kb/application/service/QaApplicationService.java`
- [Conversation state](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/domain/conversation/Conversation.java): `backend/kb-service/src/main/java/com/kb/domain/conversation/Conversation.java`
- [Answer pipeline](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/application/service/AnswerPipeline.java): `backend/kb-service/src/main/java/com/kb/application/service/AnswerPipeline.java`
- [Hybrid retrieval](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/domain/rag/SearchService.java): `backend/kb-service/src/main/java/com/kb/domain/rag/SearchService.java`
- [Embedding provider](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/infrastructure/rag/embedding/OpenAiEmbeddingService.java): `backend/kb-service/src/main/java/com/kb/infrastructure/rag/embedding/OpenAiEmbeddingService.java`
- [LLM and tools](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/infrastructure/rag/llm/LangChain4jLlmService.java): `backend/kb-service/src/main/java/com/kb/infrastructure/rag/llm/LangChain4jLlmService.java`
- [Document ingestion](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/application/service/DocumentApplicationService.java): `backend/kb-service/src/main/java/com/kb/application/service/DocumentApplicationService.java`
- [Search index](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/infrastructure/persistence/elasticsearch/EsIndexService.java): `backend/kb-service/src/main/java/com/kb/infrastructure/persistence/elasticsearch/EsIndexService.java`
- [Vector store](https://github.com/aliens983/campusbrain/tree/main/backend/kb-service/src/main/java/com/kb/infrastructure/persistence/qdrant): `backend/kb-service/src/main/java/com/kb/infrastructure/persistence/qdrant`
- [Appointment tool](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/infrastructure/rag/tool/AppointmentTool.java): `backend/kb-service/src/main/java/com/kb/infrastructure/rag/tool/AppointmentTool.java`
- [Answer caches](https://github.com/aliens983/campusbrain/blob/main/backend/kb-service/src/main/java/com/kb/infrastructure/cache/SemanticCacheService.java): `backend/kb-service/src/main/java/com/kb/infrastructure/cache/SemanticCacheService.java`

### Campus appointments

- [CAS assistant API](https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/interfaces/controller/assistant/AppointmentAssistantController.java): `backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/interfaces/controller/assistant/AppointmentAssistantController.java`
- [Appointment assistant](https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/AppointmentAssistantService.java): `backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/AppointmentAssistantService.java`
- [Booking lifecycle](https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/BookServiceImpl.java): `backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/BookServiceImpl.java`
- [Campus service catalog](https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/ServiceItemServiceImpl.java): `backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/ServiceItemServiceImpl.java`
- [Consultation chat](https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/ConsultChatServiceImpl.java): `backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/impl/ConsultChatServiceImpl.java`
- [Appointment events](https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/infrastructure/mq/BookingEventPublisher.java): `backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/infrastructure/mq/BookingEventPublisher.java`

### Identity and services

- [API gateway](https://github.com/aliens983/campusbrain/blob/main/backend/gateway/src/main/java/com/laoliu/gateway/GatewayApplication.java): `backend/gateway/src/main/java/com/laoliu/gateway/GatewayApplication.java`
- [Account and RBAC](https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-system/src/main/java/com/laoliu/cas/system/application/service/AuthService.java): `backend/cas-service/cas-module-system/src/main/java/com/laoliu/cas/system/application/service/AuthService.java`
- [Email service](https://github.com/aliens983/campusbrain/blob/main/backend/cas-service/cas-module-infra-api/src/main/java/com/laoliu/cas/infra/api/email/EmailService.java): `backend/cas-service/cas-module-infra-api/src/main/java/com/laoliu/cas/infra/api/email/EmailService.java`

### Other components

- **Campus user**

## Connections

- Campus user → Vue application: uses (evidence: `README.md`)
- Vue application → API gateway: calls APIs (evidence: `README.md`)
- API gateway → QA endpoint: routes requests
- QA endpoint → QA orchestration: delegates
- QA orchestration → Conversation state: maintains context (evidence: `backend/kb-service/src/main/java/com/kb/application/service/QaApplicationService.java`)
- QA orchestration → Answer pipeline: retrieves and generates (evidence: `backend/kb-service/src/main/java/com/kb/application/service/QaApplicationService.java`)
- Answer pipeline → Hybrid retrieval: retrieves
- Hybrid retrieval → Search index: keyword search
- Hybrid retrieval → Vector store: vector search
- Hybrid retrieval → Embedding provider: embeds queries
- Answer pipeline → LLM and tools: generates answers
- Document ingestion → Embedding provider: embeds chunks
- Document ingestion → Search index: indexes documents
- Document ingestion → Vector store: stores vectors
- LLM and tools → Appointment tool: calls tools (evidence: `backend/kb-service/src/main/java/com/kb/infrastructure/rag/llm/LangChain4jLlmService.java`)
- Appointment tool → CAS assistant API: queries CAS (evidence: `README.md`)
- CAS assistant API → Appointment assistant: delegates
- Appointment assistant → Booking lifecycle: confirms drafts (evidence: `backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/AppointmentAssistantService.java`)
- Appointment assistant → Campus service catalog: queries services (evidence: `backend/cas-service/cas-module-appointment/src/main/java/com/laoliu/cas/appointment/application/service/AppointmentAssistantService.java`)
- Campus user → Booking lifecycle: books services (evidence: `README.md`)
- Booking lifecycle → Appointment events: publishes changes (evidence: `README.md`)
- Appointment events → Answer caches: invalidates caches (evidence: `README.md`)
- Campus user → Consultation chat: messages teacher (evidence: `README.md`)
- Campus user → Account and RBAC: authenticates (evidence: `README.md`)
- Booking lifecycle → Email service: sends review notices (evidence: `README.md`)