How openhay-ai/openhay works
Project type and purpose
• OpenHay is a self-hostable, full-stack AI knowledge exploration platform with a React/TypeScript frontend and a Python/FastAPI backend.
• It offers Q&A with citations, autonomous news gathering, deep research agents, and document translation—all via LLMs and web APIs.
File structure
• Top-level:
• assets (logo, static images)
• backend (FastAPI service, agents, services, repositories, database schema)
• frontend (React + Vite + Tailwind UI component library)
• Backend:
• api/routers – HTTP endpoints (auth, chat, contact, featured, health, metrics, research, translate)
• core/agents – autonomous agents (chat, discover, research, translate)
• core/services – wrappers around LLM invocations, web search, email, streaming, rate limiting
• core/repositories – persistence layer for articles, conversations, messages, suggestions
• db.py & db_schema.sql – database connection & schema
• settings.py & env.example – configuration management
• Frontend:
• src/pages – route-driven React pages (Dashboard, FeatureChat, History, Research, Translate)
• src/lib – API client, auth helpers, utility functions
• src/components – UI building blocks, layout, translation uploader
• public/index.html & Caddyfile – hosting config
• package.json & Vite config – build pipelines
README for additional insights
• Core features described with pointers to specialized agent READMEs.
• Bring-your-own-key model for Google AI (Gemini), Brave API.
• Separate setup guides for frontend & backend.
a. Main Components
• Frontend React App (deployed via Vite/Caddy)
• Backend FastAPI Service (Docker container)
• Agent Engine (in-process Python modules under core/agents)
• Persistence Store (PostgreSQL/MySQL/SQLite per db_schema.sql)
• External Services:
– LLM Providers (Google Gemini)
– Web Search API (Brave API)
– Email SMTP (optional)
b. Relationships & Interactions
• User → Frontend: UI interactions in browser
• Frontend → Backend: REST calls to /api/* endpoints over HTTPS
• Backend API layer → Core agents/services: function/module calls
• Core services → External APIs: HTTP calls to LLM & search providers
• Backend → Database: SQL operations via repositories
c. Architectural Patterns & Principles
• Layered Architecture: API routers → Core services → Repositories → DB
• Modular Agents: each feature (chat, discover, research, translate) encapsulated in its own module
• Dependency Injection (FastAPI) for services & rate limiting
• Bring-your-own-key decouples credentials from code
d. Key Technologies & Frameworks
• Frontend: React, TypeScript, Vite, Tailwind CSS, Headless UI, shadcn/ui components
• Backend: Python 3.x, FastAPI, SQLAlchemy (implied), Pydantic models, Docker
• CI: pre-commit, conventional commits