How hadryan/maxkb works
Main Components
• Frontend Interface: The “ui” directory shows a Vue.js application with views, components, routing, and state management. Represent it as the client layer that interacts (via HTTP/HTTPS API calls) with the backend.
• Backend Services: The “apps” directory is organized as multiple Django apps. Key ones include:
– “application”: Contains chat pipeline management (with multiple steps, such as “chat_step”, “generate_human_message_step”, etc.) and flow orchestration logic.
– “dataset”: Handles document ingestion, parsing, and dataset management.
– “embedding”: Manages text embedding and vector search (leveraging pgvector).
– “function_lib”: Contains additional AI function libraries.
– “setting”: Manages configuration for system settings and model provider integrations.
– “users” and “smartdoc”: Cover authentication/user management and additional document-based functionality.
• Workflow Engine / Chat Pipeline: Notice the detailed structure within “apps/application/chat_pipeline” and “apps/application/flow”, as well as multiple “step_node” directories; these represent the orchestration and execution of different AI/LLM steps.
• Model Providers & LLM Integrations: Under “apps/setting/models_provider”, numerous implementations for different model providers (e.g., OpenAI, Anthropic, Azure, etc.) show that MaxKB supports model-agnostic integration.
• Common Services: Directories like “apps/common” cover cross-cutting services (authentication, caching, logging, event handling, middleware, locks, and SQL queries). They are central to system reliability and performance.
• Infrastructure/Deployment: Supplementary files such as Dockerfiles (in “installer”), GitHub workflows, and CI/CD scripts indicate containerized deployment and automated build/deployment processes.
Relationships and Interactions
• Chat pipeline and flow engine as specialized subcomponents that orchestrate the conversation logic (including steps like generating human messages, resetting problems, and search dataset steps) via well-defined interfaces.
• If applicable, include a “Task/Job” component (visible in directories like “apps/common/task”, “apps/ops/celery”) to show asynchronous processing, scheduling, and background jobs.
Architectural Patterns & Design Principles
• Modular design with each Django “app” encapsulating a bounded context (e.g., dataset management, user management, embedding).
• Workflow orchestration pattern used in the “flow” directories. This demonstrates loosely coupled components following the command or pipeline pattern.
• Use of dependency injection and DRY principles in common modules, middleware, and handle/encoder/util packages.
• Containerization and automated CI/CD pipelines that ensure reproducible deployments.
Detailed Elements
• Modules/Clusters: Group related Django apps (e.g., all application-related components under one cluster, dataset/embedding under another).
• Additional Elements: Show deployment artifacts like Docker and installer setups lightly on the side to present the containerized deployment workflow.
• At the top level, separate “Frontend” from “Backend”.
• Under “Backend”, have clusters/blocks for:
– Core Business Logic (Application/Chat Pipeline & Workflow)
– Data Management (Dataset, Embedding, Function Library)
– Configuration & Model Settings (Setting/Models Provider)
– Supporting Infrastructure (Common utilities, auth, caching)
• These to the “Database” module.