# mimisukemaster/ai-voicevox architecture

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

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

## Overview

##### Main Components
a. Browser Client
- Pages:
- “/” (AI-討論) – index.html + client.js + styles.css
- “/question” (AI-ずんだもん) – question/index.html + question/client.js
- “/about” – about/index.html
b. Static Assets Server
- Serves everything under /public (HTML, CSS, JS, fonts, images, TtsQuestV3Voicevox.js)
c. Express Back End (server.js)
- Endpoints: GET static files, POST /api/debate, POST /api/question, etc.
- Reads .env for GEMINI_API_KEY, COHERE_API_KEY, VOICEVOX_API_KEY, plus “useLocal” flag.
- Orchestrates calls to LLMs and TTS engine.
d. External LLM Services
- Google Gemini API
- Cohere (for CommandR)
e. Voicevox TTS Engine
- Remote (Streaming): TtsQuestV3Voicevox.js module calls the streaming API endpoint
- Optional Local: Developer-run Voicevox Engine on localhost:50021
f. Deployment Platform
- Vercel (vercel.json config): server.js runs as a serverless function; public folder served as static hosting.

##### Relationships & Data Flows
- User interacts in browser → client.js issues XHR/Fetch to Express (serverless).
- Express receives request →
– Calls Gemini and/or Cohere API (HTTP).
– Aggregates responses, builds debate turn or answer.
– Invokes TtsQuestV3Voicevox.js to stream audio from Voicevox (remote or local).
- Express streams back audio + JSON metadata to client.
- Browser client plays audio and updates UI in real time.

##### Architectural Patterns
- Monolith / Single serverless function: Express handles both static and API routes.
- Proxy pattern: backend proxies browser requests to LLMs and TTS services.
- Streaming data flow: audio is streamed from TtsQuestV3Voicevox.js to client.
- Feature flag: “ローカルAPIを使う” toggles between remote Voicevox vs. local engine.

##### Relevant Technologies & Frameworks
- Node.js + Express
- Vercel (serverless deployment)
- @google/generative-ai, cohere-ai SDKs
- dotenv for config
- TtsQuestV3Voicevox.js (streaming TTS library)
- Plain HTML/CSS/Vanilla JS for front end

##### Detailed Component Breakdown (to include
- .env / vercel.json / package.json (configuration)
- server.js (Express entry point)
- public/
- index.html & client.js (Debate)
- question/index.html & client.js (Q&A)
- about/index.html
- styles.css, TtsQuestV3Voicevox.js, fonts, images
- External flows:
- HTTP POST → /api/debate
- HTTP POST → /api/question
- HTTP GET → static assets
- Conditional branch: if “localAPI” flag → call http://localhost:50021; else → call streaming API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Debate["Client: Debate Page (/)"]:::client
        Question["Client: Question Page (/question)"]:::client
        About["Client: About Page (/about)"]:::client
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        StaticHandler["Static File Handler"]:::server
        APIRouter["API Router (/api/debate, /api/question)"]:::server
        BizLogic["Business Logic"]:::server
        TTSModule["TTS Module"]:::server
        subgraph "Configuration" 
            direction TB
            Env[".env / package.json"]:::config
            VercelCfg["vercel.json"]:::config
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Gemini["Google Gemini API"]:::external
        Cohere["Cohere API"]:::external
        VoicevoxRemote["Voicevox Streaming API"]:::external
        VoicevoxLocal["Voicevox Local Engine (http://localhost:50021)"]:::external
    end

    %% Static Assets
    subgraph "Static Assets"
        direction TB
        Assets["public/"]:::assets
        Fonts["Fonts"]:::assets
        Images["Images"]:::assets
    end

    %% Data Flows
    Debate -->|"GET static"| StaticHandler
    Question -->|"GET static"| StaticHandler
    About -->|"GET static"| StaticHandler
    StaticHandler -->|"serves HTML/CSS/JS"| Debate
    StaticHandler -->|"serves HTML/CSS/JS"| Question
    StaticHandler -->|"serves HTML"| About

    Debate -->|"POST /api/debate"| APIRouter
    Question -->|"POST /api/question"| APIRouter
    APIRouter -->|"process request"| BizLogic
    BizLogic -->|"call"| Gemini
    BizLogic -->|"call"| Cohere
    BizLogic -->|"invoke"| TTSModule
    TTSModule -->|"stream audio"| VoicevoxRemote
    TTSModule -->|"stream audio"| VoicevoxLocal
    TTSModule -->|"stream audio+JSON"| Debate
    TTSModule -->|"stream audio+JSON"| Question

    %% Configuration and Deployment
    APIRouter --> Env
    APIRouter --> VercelCfg

    %% Click Events
    click Debate "https://github.com/mimisukemaster/ai-voicevox/blob/main/public/index.html"
    click Question "https://github.com/mimisukemaster/ai-voicevox/blob/main/public/question/index.html"
    click About "https://github.com/mimisukemaster/ai-voicevox/blob/main/public/about/index.html"
    click Assets "https://github.com/mimisukemaster/ai-voicevox/tree/main/public/"
    click Fonts "https://github.com/mimisukemaster/ai-voicevox/tree/main/public/fonts/"
    click Images "https://github.com/mimisukemaster/ai-voicevox/tree/main/public/images/"
    click TTSModule "https://github.com/mimisukemaster/ai-voicevox/blob/main/public/TtsQuestV3Voicevox.js"
    click APIRouter "https://github.com/mimisukemaster/ai-voicevox/blob/main/server.js"
    click Env "https://github.com/mimisukemaster/ai-voicevox/blob/main/package.json"
    click VercelCfg "https://github.com/mimisukemaster/ai-voicevox/blob/main/vercel.json"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085;
    classDef server fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef assets fill:#f8d7da,stroke:#721c24,color:#721c24;
```
