How khoantd/haiven works
Project’s Purpose and Type
• The README explains that Haiven is an “accelerator” for piloting AI assistance in software delivery teams. It is not a production-scale product but a sandbox with a “one-container” deployment strategy.
• Its core purpose is to integrate with popular cloud-based LLM providers (Azure OpenAI, AWS Bedrock, Google Gemini) or even local providers like Ollama to help codify and deliver team-specific practices and knowledge (via “knowledge packs”).
• The project includes multiple components: a Python-based backend (with modules for API endpoints, configuration, LLM and embeddings handling, knowledge management), a modern React/Next.js UI, and a CLI for additional integrations and scripting.
File Structure
• The top-level of the project contains several “policy and configuration” files (.dockerignore, .pre-commit-config.yaml, etc.) and directories for GitHub workflows, documentation, and licensing.
• Key top-level folders are:
• app: Contains the main backend code (the core API, integration with language models, embedding management, configuration, and business logic).
• ui: A Next.js/React frontend with dedicated pages, components, assets, and tests.
• cli: A command-line interface that mirrors some of the application’s functionality through a separate Python package.
• docs: Architectural decision records and design documentation that further explain deployment choices and knowledge pack integration.
• devscripts: Additional tooling scripts for development and testing.
• The backend is modularized into sub-folders like “api” for endpoints, “knowledge” and “embeddings” for handling various AI and data-specific functionalities, “llms” for model integration, and “config” for constants and config handling.
• Environment-specific configuration files (app/.env.*.template) stress that deployment requires plugging in provider-specific credentials.
• UI Frontend (located in the “ui” folder):
• Built with React/Next.js (including pages, components, styles, and hooks).
• Communicates with the backend (over REST or SSE as indicated by the presence of files like _fetch_sse.js).
• Backend/API (located in the “app” folder):
• Main entry point in app/app.py and/or app/server.py.
• API endpoints exposed via the “api” folder.
• Orchestrates business logic, configuration (app/config.yaml), and service invocations.
• Integrates with “knowledge_manager”, “embeddings”, “llms”, “prompts”, etc.
• Contains in-memory operations and logging for persistence.
• External Providers and LLM Integrations:
• External AI providers (Azure, AWS, Google, Ollama) as distinct components.
• The integration details are set in app/config.yaml and via environment variables.
• Knowledge Pack:
• Mounted externally (via Docker volume as shown in the “docker run” examples) so that the backend can load and work with team-specific prompts and guidance data.
• CLI Component:
• Resides in the “cli” folder and encapsulates similar functionality to the web app but provides another way to interact with the services.
• Development Scripts:
• For completeness, include a “devscripts” component for tasks like dependency updates and testing.
Architectural Patterns and Design Principles
• The design embraces modularity and a separation of concerns:
• Frontend vs. Backend separation.
• Logical separation within the backend (APIs, LLM functions, embeddings, configuration, and logging).
• External dependencies (cloud APIs, local model services) are clearly separated via environment configurations.
Final Recommendations for the Principal Software Engineer
• Drill down into the backend components (e.g., API endpoints, knowledge management, LLM integrations) if necessary.
• Refer to the configuration files (.env templates, app/config.yaml) and documentation (docs/design.md, docs/knowledge_packs.md) to capture any nuances of the runtime environment and customizations.