# chihiroyoshizumi/hot-oss-agent architecture

> Architecture diagram of the GitHub repository chihiroyoshizumi/hot-oss-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chihiroyoshizumi/hot-oss-agent
- Repository: https://github.com/chihiroyoshizumi/hot-oss-agent

## Overview

##### Project type and purpose
- This is a full-stack web application built on Laravel (PHP) with a React/TypeScript front-end delivered via Inertia/Vite.
- Purpose: Collect trending OSS data from OSS Insight and GitHub, feed it to an LLM-based agent framework (LarAgent) to auto-generate repository summaries, and surface these in a web UI or via console commands.

##### File structure
- Top-level directories:
- app – core PHP code (Agents, Drivers, Services, DataObjects, Console commands, HTTP Controllers)
- resources/js – front-end React/TS pages, utilities, SSR entry
- routes – web.php and console.php for HTTP endpoints and Artisan commands
- config – environment-specific settings for cache, queue, external APIs, LarAgent, Inertia
- database – migrations, factories, seeders for Users, jobs, cache tables
- public – web root (index.php) and static assets
- tests – Feature and Unit tests
- Architectural patterns:
- MVC in Laravel (Models, Views, Controllers)
- Inertia as the glue between PHP controllers and React views
- Console scheduler / Artisan command for batch summary generation
- Service layer (OssInsightClient, RepositoryDocumentationFetcher, RepositorySummarizer)
- Agent‐based orchestration under app/AiAgents with pluggable Tools and Drivers

##### README for additional insights
- External dependencies: OSS Insight API, GitHub docs, multiple LLM providers (OpenAI, Gemini, UpStage, Tavily, X_API)
- Run modes: web UI (via Sail or local PHP server), CLI (`php artisan app:oss-trending-summaries`)
- Configurable options: period, language, limit

##### Detail without over-segmentation
- Every logical component (Controllers, Services, Agents, Drivers)
- External dependencies (OSS Insight, GitHub, LLMs)
- Scheduled vs. on-demand flows distinctly

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "Browser Layer"
        BROWSER["User's Browser\n(React/TypeScript)"]:::internal
        ENTRY["Entry Point\napp.tsx"]:::internal
        PAGES["Pages\nwelcome.tsx"]:::internal
        UTIL["Utilities\nutils.ts"]:::internal
        SSR["SSR Bootstrap\nssr.tsx"]:::internal
        TYPES["Type Definitions"]:::internal
        VITE["Vite Config\nvite.config.ts"]:::internal
    end

    %% Backend Layer
    subgraph "Backend Layer (Laravel)"
        subgraph "HTTP Layer"
            ROUTES_WEB["Web Routes\nroutes/web.php"]:::internal
            CONTROLLERS["Controllers\napp/Http/Controllers"]:::internal
            INERTIA_MW["Inertia Middleware\nHandleInertiaRequests.php"]:::internal
        end

        subgraph "Agent Engine"
            BASE_AGENT["BaseAgent\napp/AiAgents/BaseAgent.php"]:::internal
            REPO_AGENT["RepositorySummaryAgent\napp/AiAgents/RepositorySummaryAgent.php"]:::internal
            subgraph "Tools & Drivers"
                TAVILY_TOOL["TavilySearchTool\napp/AiAgents/Tools/TavilySearchTool.php"]:::internal
                UPSTAGE_DRIVER["UpStageDriver\napp/Drivers/UpStageProvider/UpStageDriver.php"]:::internal
            end
        end

        subgraph "Services"
            OSS_CLIENT["OssInsightClient\napp/Services/OssInsightClient.php"]:::internal
            DOC_FETCHER["RepositoryDocumentationFetcher\napp/Services/RepositoryDocumentationFetcher.php"]:::internal
            SUMMARIZER["RepositorySummarizer\napp/Services/RepositorySummarizer.php"]:::internal
        end

        subgraph "Data Layer"
            TREND_OBJ["TrendingRepository\napp/DataObjects/TrendingRepository.php"]:::internal
            USER_MODEL["User Model\napp/Models/User.php"]:::internal
            DATABASE["Database\n(MySQL/PostgreSQL)"]:::infra
        end

        subgraph "Scheduler / CLI"
            ROUTES_CLI["Console Routes\nroutes/console.php"]:::internal
            SCHEDULER["SummarizeTrendingRepositories Command\napp/Console/Commands/SummarizeTrendingRepositories.php"]:::internal
        end
    end

    %% External Services
    subgraph "External Services" 
        OSS_API["OSS Insight API"]:::external
        GITHUB_API["GitHub API"]:::external
        subgraph "LLM Providers"
            OPENAI["OpenAI"]:::external
            GEMINI["Gemini"]:::external
            UPSTAGE["UpStage"]:::external
            TAVILY["Tavily"]:::external
            XAPI["X_API"]:::external
        end
    end

    %% Infrastructure
    subgraph "Infrastructure"
        DOCKER["Docker/Sail"]:::infra
        QUEUE["Queue System"]:::infra
    end

    %% Relationships
    BROWSER -->|"HTTP/JSON (Inertia)"| ROUTES_WEB
    ROUTES_WEB --> CONTROLLERS
    CONTROLLERS --> INERTIA_MW
    INERTIA_MW --> PAGES
    PAGES --> ENTRY
    PAGES --> UTIL
    PAGES --> SSR
    ENTRY --> TYPES
    ENTRY --> VITE

    CONTROLLERS -->|calls| OSS_CLIENT
    CONTROLLERS -->|calls| DOC_FETCHER
    CONTROLLERS -->|calls| SUMMARIZER

    OSS_CLIENT --> OSS_API
    DOC_FETCHER --> GITHUB_API
    SUMMARIZER --> BASE_AGENT
    BASE_AGENT --> REPO_AGENT
    REPO_AGENT --> TAVILY_TOOL
    REPO_AGENT --> UPSTAGE_DRIVER
    REPO_AGENT --> OPENAI
    REPO_AGENT --> GEMINI
    REPO_AGENT --> UPSTAGE
    REPO_AGENT --> TAVILY
    REPO_AGENT --> XAPI

    SCHEDULER -->|triggers| BASE_AGENT
    ROUTES_CLI --> SCHEDULER

    OSS_CLIENT --> DATABASE
    DOC_FETCHER --> DATABASE
    SUMMARIZER --> DATABASE
    REPO_AGENT --> TREND_OBJ
    CONTROLLERS --> USER_MODEL

    DATABASE --> USER_MODEL

    DOCKER --> BROWSER
    DOCKER --> CONTROLLERS
    QUEUE -.-> SCHEDULER

    %% Click Events
    click CONTROLLERS "https://github.com/chihiroyoshizumi/hot-oss-agent/tree/main/app/Http/Controllers"
    click INERTIA_MW "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/Http/Middleware/HandleInertiaRequests.php"
    click ROUTES_WEB "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/routes/web.php"
    click ROUTES_CLI "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/routes/console.php"
    click SCHEDULER "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/Console/Commands/SummarizeTrendingRepositories.php"
    click BASE_AGENT "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/AiAgents/BaseAgent.php"
    click REPO_AGENT "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/AiAgents/RepositorySummaryAgent.php"
    click TAVILY_TOOL "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/AiAgents/Tools/TavilySearchTool.php"
    click UPSTAGE_DRIVER "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/Drivers/UpStageProvider/UpStageDriver.php"
    click OSS_CLIENT "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/Services/OssInsightClient.php"
    click DOC_FETCHER "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/Services/RepositoryDocumentationFetcher.php"
    click SUMMARIZER "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/Services/RepositorySummarizer.php"
    click TREND_OBJ "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/DataObjects/TrendingRepository.php"
    click USER_MODEL "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/Models/User.php"
    click ENTRY "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/resources/js/app.tsx"
    click PAGES "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/resources/js/pages/welcome.tsx"
    click UTIL "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/resources/js/lib/utils.ts"
    click SSR "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/resources/js/ssr.tsx"
    click TYPES "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/resources/js/types/global.d.ts"
    click TYPES "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/resources/js/types/index.d.ts"
    click TYPES "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/resources/js/types/vite-env.d.ts"
    click VITE "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/vite.config.ts"
    click INERTIA_MW "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/config/inertia.php"
    click SUMMARIZER "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/config/laragent.php"
    click OSS_API "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/config/services.php"
    click DATABASE "https://github.com/chihiroyoshizumi/hot-oss-agent/tree/main/database/migrations"
    click DATABASE "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/database/seeders/DatabaseSeeder.php"
    click DATABASE "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/database/factories/UserFactory.php"
    click ROUTES_CLI "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/tests/Feature/SummarizeTrendingRepositoriesTest.php"
    click BASE_AGENT "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/tests/Feature/BaseAgentEngineErrorTest.php"
    click ROUTES_CLI "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/tests/Feature/ExampleTest.php"
    click BASE_AGENT "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/tests/Unit/ExampleTest.php"
    click DATABASE "https://github.com/chihiroyoshizumi/hot-oss-agent/blob/main/app/Providers/AppServiceProvider.php"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#005cbf,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef infra fill:#fff3cd,stroke:#856404,color:#856404
```
