# sndraw/bookroom architecture

> Architecture diagram of the GitHub repository sndraw/bookroom, 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/sndraw/bookroom
- Repository: https://github.com/sndraw/bookroom

## Overview

##### Main Components
a. Frontend (Bookroom Web)
- Located in the bookroom-web directory.
- Built using React (or similar in modern JavaScript frameworks) with a rich set of pages/components (Agent, ChatPanel, Graph, Document, etc.).
- Responsible for user interaction and presenting data (UI) from the backend.
b. Backend API (Bookroom API)
- Located in the bookroom-api directory.
- Organizes structural layers including controllers, services, models, routers, middleware, utilities, and various SDKs (for agents, search, file handling, etc.).
- Implements API endpoints for different features (user management, intelligent assistants, file handling, etc.).
c. Deployment Infrastructure (Docker Deploy)
- The docker-deploy folder contains Docker-compose files, environment configurations, and initialization scripts.
- Manages containerization and orchestration of the services, including API, web application, and other middleware (e.g., minio, possibly database initialization).
d. External Integration Components
- Model Deployment: Integration with third-party services such as Ollama, OpenAI, LightRAG.
- Intelligent Assistants and Search Services: Modules for Agents SDK, MCP SDK, custom search engines, etc.
- Additional microservices such as voice and device management (future components for BookRoom Audio, BookRoom Robot).

##### Out Interactions & Data Flow
a. UI Layer (Frontend)
- Presents the user interface and interacts with backend API endpoints.
- Uses routes present in the web application’s router configuration.
b. API Layer (Backend)
- Controllers receive requests from the frontend and coordinate with services.
- Services interact with models (data storage) and external SDK modules, managing business logic.
- Middlewares (auth, parameters, JWT, setup, etc.) provide security, authorization, and request validation.
- Common utilities (file, logger, crypto, request handling) support cross-cutting concerns.
c. External Services
- The API makes outbound calls to external model endpoints or SDKs (as specified in the README) – e.g., OpenAI, Ollama, LightRAG.
- SDK subdirectories encapsulate the logic for interacting with these external services.
- The secure configuration and deployment environments (using Docker containers) abstract away platform-specific details.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Clear division between frontend (presentation) and backend (application logic and data management).
- Modular Design: The API is split into modules (controllers, services, models, middleware) and SDK implementations which help in maintaining and extending functionality.
- Containerization: Extensive use of Docker and Docker Compose ensures consistent and scalable deployment across various environments.
- Extendibility: The inclusion of multiple SDK directories and configuration files indicates that the system is designed to integrate several external services and protocols, easing future enhancements.

##### Additional Notes for the Principal Software Engineer
- Be detailed when labeling each component; ensure that components such as “AIChatController,” “AgentService,” and corresponding SDK folders are conceptualized under an overall “API” layer.
- Middleware components (auth, JWT) that enforce security and proper data flow.
- Out the integration points based on the README’s “系统配置示例” (system configuration examples for model platforms and search engines) to capture real-world interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        FE["Bookroom Web"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API"
        BEAPI["Backend API"]:::backend
        Controllers["Controllers"]:::backend
        Services["Services"]:::backend
        Models["Models"]:::backend
        Middlewares["Middlewares"]:::backend
        subgraph "SDK Integrations"
            AgentSDK["Agent SDK"]:::sdk
            OpenAISDK["OpenAI SDK"]:::sdk
            OllamaSDK["Ollama SDK"]:::sdk
            LightRAGSDK["LightRAG SDK"]:::sdk
            MinioIntegration["Minio Integration"]:::sdk
            SearchSDKs["Search SDKs"]:::sdk
        end
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        D["Docker Deploy"]:::deployment
    end

    %% External Services/Model Platforms
    subgraph "External Services"
        ExternalOpenAI["OpenAI"]:::external
        ExternalOllama["Ollama"]:::external
        ExternalLightRAG["LightRAG"]:::external
    end

    %% Connections
    FE -->|"calls"| Controllers
    Controllers -->|"delegates"| Services
    Controllers -->|"filtersThrough"| Middlewares
    Services -->|"queries"| Models
    Services --> AgentSDK
    Services --> OpenAISDK
    Services --> OllamaSDK
    Services --> LightRAGSDK
    Services --> MinioIntegration
    Services --> SearchSDKs
    OpenAISDK -->|"integrates"| ExternalOpenAI
    OllamaSDK -->|"integrates"| ExternalOllama
    LightRAGSDK -->|"integrates"| ExternalLightRAG
    D -->|"orchestrates"| FE
    D -->|"orchestrates"| BEAPI

    %% Click Events
    click FE "https://github.com/sndraw/bookroom/tree/main/bookroom-web/"
    click BEAPI "https://github.com/sndraw/bookroom/tree/main/bookroom-api/"
    click Controllers "https://github.com/sndraw/bookroom/tree/main/bookroom-api/api/controller/"
    click Services "https://github.com/sndraw/bookroom/tree/main/bookroom-api/api/service/"
    click Models "https://github.com/sndraw/bookroom/tree/main/bookroom-api/api/models/"
    click Middlewares "https://github.com/sndraw/bookroom/tree/main/bookroom-api/api/middlewares/"
    click AgentSDK "https://github.com/sndraw/bookroom/tree/main/bookroom-api/api/SDK/agent/"
    click OpenAISDK "https://github.com/sndraw/bookroom/tree/main/bookroom-api/api/SDK/openai/"
    click OllamaSDK "https://github.com/sndraw/bookroom/tree/main/bookroom-api/api/SDK/ollama/"
    click LightRAGSDK "https://github.com/sndraw/bookroom/tree/main/bookroom-api/api/SDK/lightrag/"
    click MinioIntegration "https://github.com/sndraw/bookroom/tree/main/bookroom-api/api/SDK/minio/"
    click SearchSDKs "https://github.com/sndraw/bookroom/tree/main/bookroom-api/api/SDK/search/"
    click D "https://github.com/sndraw/bookroom/tree/main/docker-deploy/"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#1F78B4,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef deployment fill:#FFECB3,stroke:#FF9800,stroke-width:2px;
    classDef external fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;
    classDef sdk fill:#E1BEE7,stroke:#9C27B0,stroke-width:2px;
```
