# openhay-ai/openhay architecture

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

- Interactive diagram: https://gitdiagram.com/openhay-ai/openhay
- Repository: https://github.com/openhay-ai/openhay

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    User["User"]:::user

    %% Frontend Container
    subgraph "Frontend (React + Vite)" 
        direction TB
        FEApp["Frontend App"]:::frontend
        subgraph "Pages"
            direction TB
            Dash["Dashboard"]:::page
            ChatPage["FeatureChat"]:::page
            Hist["History"]:::page
            Res["Research"]:::page
            Trans["Translate"]:::page
        end
        FEComponents["UI Components"]:::frontend
        FEHelpers["API Client & Auth Helpers"]:::frontend
        FEConfig["Hosting Config (Caddyfile & index.html)"]:::config
        FEEnv["Env Example"]:::config
        FEApp -->|routes to| Dash
        FEApp -->|routes to| ChatPage
        FEApp -->|routes to| Hist
        FEApp -->|routes to| Res
        FEApp -->|routes to| Trans
        FEApp -->|uses| FEComponents
        FEApp -->|calls| FEHelpers
        FEApp -->|deployed with| FEConfig
        FEApp -->|configured by| FEEnv
    end

    %% Backend Container
    subgraph "Backend (FastAPI)" 
        direction TB
        APIMain["API Entry Point"]:::backend
        subgraph "API Routers"
            direction TB
            AuthR["auth.py"]:::router
            ChatR["chat.py"]:::router
            ContactR["contact.py"]:::router
            FeaturedR["featured.py"]:::router
            HealthR["health.py"]:::router
            MetricsR["metrics.py"]:::router
            ResearchR["research.py"]:::router
            TranslateR["translate.py"]:::router
        end
        subgraph "Core Agents"
            direction TB
            AgentChat["Chat Agent"]:::agent
            AgentDisc["Discover Agent"]:::agent
            AgentRes["Research Agent"]:::agent
            AgentTrans["Translate Agent"]:::agent
        end
        subgraph "Core Services"
            direction TB
            SvcLLM["LLM Invoker"]:::service
            SvcWeb["Web Discovery"]:::service
            SvcEmail["Email Service"]:::service
            SvcStream["Streaming"]:::service
            SvcRate["Rate Limiting"]:::service
            SvcChat["Chat Service"]:::service
            SvcTrans["Translation Service"]:::service
        end
        subgraph "Repositories"
            direction TB
            RepoArticle["Article Repo"]:::repo
            RepoConv["Conversation Repo"]:::repo
            RepoMsg["Message Repo"]:::repo
            RepoSug["Daily Suggestion Repo"]:::repo
        end
        DBSchema["DB Schema"]:::db
        DBConn["DB Connection"]:::db
        Settings["Settings & Env"]:::config
        Docker["Backend Dockerfile"]:::config

        APIMain -->|includes routers| AuthR & ChatR & ContactR & FeaturedR & HealthR & MetricsR & ResearchR & TranslateR
        AuthR & ChatR & ContactR & FeaturedR & HealthR & MetricsR & ResearchR & TranslateR -->|invoke| AgentChat & AgentDisc & AgentRes & AgentTrans & SvcChat & SvcTrans
        AgentChat & AgentDisc & AgentRes & AgentTrans -->|call| SvcLLM & SvcWeb
        SvcEmail & SvcStream & SvcRate -->|used by| AgentRes & AgentChat
        SvcChat & SvcTrans -->|persist| RepoArticle & RepoConv & RepoMsg & RepoSug
        RepoArticle & RepoConv & RepoMsg & RepoSug -->|SQL| DBConn
        DBConn -->|schema| DBSchema
        APIMain -->|loads| Settings
        APIMain -->|built by| Docker
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLM["LLM Providers"]:::external
        SearchAPI["Web Search API"]:::external
        SMTP["Email SMTP"]:::external
        Vault["API Keys Vault"]:::external
    end

    AgentChat & AgentDisc & AgentRes & AgentTrans -->|async call| LLM
    AgentDisc -->|async call| SearchAPI
    SvcEmail -->|SMTP send| SMTP
    Settings -->|reads keys| Vault

    %% Client-Server Boundary
    User -->|interacts via browser| FEApp
    FEApp -->|HTTPS REST| APIMain

    %% Click Events
    click FEApp "https://github.com/openhay-ai/openhay/tree/main/frontend/src"
    click FEApp "https://github.com/openhay-ai/openhay/blob/main/frontend/src/main.tsx"
    click Dash "https://github.com/openhay-ai/openhay/blob/main/frontend/src/pages/Dashboard.tsx"
    click ChatPage "https://github.com/openhay-ai/openhay/blob/main/frontend/src/pages/FeatureChat.tsx"
    click Hist "https://github.com/openhay-ai/openhay/blob/main/frontend/src/pages/History.tsx"
    click Res "https://github.com/openhay-ai/openhay/blob/main/frontend/src/pages/Research.tsx"
    click Trans "https://github.com/openhay-ai/openhay/blob/main/frontend/src/pages/Translate.tsx"
    click FEComponents "https://github.com/openhay-ai/openhay/tree/main/frontend/src/components"
    click FEHelpers "https://github.com/openhay-ai/openhay/blob/main/frontend/src/lib/api.ts"
    click FEHelpers "https://github.com/openhay-ai/openhay/blob/main/frontend/src/lib/auth.ts"
    click FEConfig "https://github.com/openhay-ai/openhay/blob/main/frontend/index.html"
    click FEConfig "https://github.com/openhay-ai/openhay/tree/main/frontend/Caddyfile"
    click FEEnv "https://github.com/openhay-ai/openhay/blob/main/frontend/env.example"

    click APIMain "https://github.com/openhay-ai/openhay/blob/main/backend/api/main.py"
    click AuthR "https://github.com/openhay-ai/openhay/blob/main/backend/api/routers/auth.py"
    click ChatR "https://github.com/openhay-ai/openhay/blob/main/backend/api/routers/chat.py"
    click ContactR "https://github.com/openhay-ai/openhay/blob/main/backend/api/routers/contact.py"
    click FeaturedR "https://github.com/openhay-ai/openhay/blob/main/backend/api/routers/featured.py"
    click HealthR "https://github.com/openhay-ai/openhay/blob/main/backend/api/routers/health.py"
    click MetricsR "https://github.com/openhay-ai/openhay/blob/main/backend/api/routers/metrics.py"
    click ResearchR "https://github.com/openhay-ai/openhay/blob/main/backend/api/routers/research.py"
    click TranslateR "https://github.com/openhay-ai/openhay/blob/main/backend/api/routers/translate.py"

    click AgentChat "https://github.com/openhay-ai/openhay/blob/main/backend/core/agents/chat/agent.py"
    click AgentDisc "https://github.com/openhay-ai/openhay/blob/main/backend/core/agents/discover/agent.py"
    click AgentRes "https://github.com/openhay-ai/openhay/blob/main/backend/core/agents/research/agent.py"
    click AgentTrans "https://github.com/openhay-ai/openhay/blob/main/backend/core/agents/translate/agent.py"

    click SvcLLM "https://github.com/openhay-ai/openhay/blob/main/backend/core/services/llm_invoker.py"
    click SvcWeb "https://github.com/openhay-ai/openhay/blob/main/backend/core/services/web_discovery.py"
    click SvcEmail "https://github.com/openhay-ai/openhay/blob/main/backend/core/services/email.py"
    click SvcStream "https://github.com/openhay-ai/openhay/blob/main/backend/core/services/streaming.py"
    click SvcRate "https://github.com/openhay-ai/openhay/blob/main/backend/core/services/ratelimit.py"
    click SvcChat "https://github.com/openhay-ai/openhay/blob/main/backend/core/services/chat.py"
    click SvcTrans "https://github.com/openhay-ai/openhay/blob/main/backend/core/services/translate.py"

    click RepoArticle "https://github.com/openhay-ai/openhay/blob/main/backend/core/repositories/article.py"
    click RepoConv "https://github.com/openhay-ai/openhay/blob/main/backend/core/repositories/conversation.py"
    click RepoMsg "https://github.com/openhay-ai/openhay/blob/main/backend/core/repositories/message.py"
    click RepoSug "https://github.com/openhay-ai/openhay/blob/main/backend/core/repositories/daily_suggestion.py"

    click DBSchema "https://github.com/openhay-ai/openhay/blob/main/backend/db_schema.sql"
    click DBConn "https://github.com/openhay-ai/openhay/blob/main/backend/db.py"
    click Settings "https://github.com/openhay-ai/openhay/blob/main/backend/settings.py"
    click Settings "https://github.com/openhay-ai/openhay/blob/main/backend/env.example"
    click Docker "https://github.com/openhay-ai/openhay/tree/main/backend/Dockerfile"
    click Vault "https://github.com/openhay-ai/openhay/blob/main/env.example"
    click DBSchema "https://github.com/openhay-ai/openhay/blob/main/backend/db_schema.sql"
    click README "https://github.com/openhay-ai/openhay/blob/main/README.md"

    %% Styles
    classDef user fill:#B3D4FC,stroke:#333,stroke-width:1px
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef page fill:#E8F4FF,stroke:#333,stroke-width:1px
    classDef config fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef backend fill:#DFF2D8,stroke:#333,stroke-width:1px
    classDef router fill:#C3E6CB,stroke:#333,stroke-width:1px
    classDef agent fill:#D1F2EB,stroke:#333,stroke-width:1px
    classDef service fill:#E2F0CB,stroke:#333,stroke-width:1px
    classDef repo fill:#FDEBD0,stroke:#333,stroke-width:1px
    classDef db fill:#FAD7A0,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
