# kaminono/echocast-workshop architecture

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

- Interactive diagram: https://gitdiagram.com/kaminono/echocast-workshop
- Repository: https://github.com/kaminono/echocast-workshop

## Overview

##### Project Type and Purpose
- EchoCast Workshop is a full-stack web application built with Next.js 15 (App Router).
- Purpose: A content-creator workstation that covers end-to-end idea collection (text & voice), AI-powered optimization, local storage, and multilingual timeline management.

##### File Structure Analysis
- **src/app/** – Next.js pages and API routes.
- API layer under `/api/asr/recognize` (speech-to-text) and `/api/ideas/optimize` (AI optimization).
- UI pages under `/ideas`, `/drafts`, `/timeline`, root pages and global layout/styles.
- **src/components/** – Reusable UI components (modals, navigation, filters).
- **src/lib/**
- `ai/` – OpenAI-compatible X1 client and wrappers.
- `asr/` – iFlytek IAT client, transports, utils.
- `indexeddb.ts` – Local DB abstraction.
- **src/types/** – Domain model & API type definitions.
- **scripts/** – CLI/test scripts for quick AI/ASR calls.
- Configuration: Next.js (`next.config.js`), Tailwind (`tailwind.config.js`), TypeScript (`tsconfig.json`), Vitest (`vitest.config.ts`).

##### Architectural Patterns & Principles
- **App Router + API Routes** – Serverless-style backend within the same Next.js project.
- **Layered Separation** – UI layer → API layer → library layer → external services.
- **Client-Server Separation** – UI and local IndexedDB on client; sensitive AI/ASR calls on server.
- **SOLID/KISS/YAGNI/DRY** – Modular code, single responsibility, minimal coupling.
- **State Machine Flow** – For voice recording → ASR → AI optimization → persistence & feedback.

##### Main Components & Interactions
a. **Frontend (Browser)**
- Next.js pages & React components render UI, modals for idea creation and voice recording.
- IndexedDB via `src/lib/indexeddb.ts` for offline storage of text and blobs.
b. **Backend/API (Next.js Server)**
- `/api/asr/recognize` route: receives base64/Buffer, invokes `IATClient` (HMAC-SHA256 via WebSocket/HTTP), returns transcript.
- `/api/ideas/optimize` route: receives text, calls X1 Chat (`openaiCompatClient`), returns optimized output.
c. **External Services**
- Starfire X1 AI model via OpenAI-compatible SDK.
- iFlytek IAT speech-to-text service.
d. **Data Stores**
- **Client**: IndexedDB for ideas (text metadata + audio Blob).
- **Volatile**: In-memory session data for streaming/recording progress.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Client
    subgraph "Browser (Client)"
        direction TB
        Layout["Layout"]:::frontend
        GlobalCSS["Global Styles"]:::frontend
        Home["Home Page"]:::frontend
        IdeasPage["Ideas Page"]:::frontend
        DraftsPage["Drafts Page"]:::frontend
        TimelinePage["Timeline Page"]:::frontend
        Container["Application Container"]:::frontend
        TopNav["Top Navigation Bar"]:::frontend
        IdeaModal["Idea Creation Modal"]:::frontend
        VoiceModal["Voice Recording Modal"]:::frontend
        SourceFilter["Source Filter"]:::frontend
        IDB["IndexedDB Storage"]:::storage
    end

    %% Server API
    subgraph "Server (Next.js API)"
        direction TB
        ASR["ASR API Route"]:::api
        OPT["AI Optimization API Route"]:::api
    end

    %% ASR Library Layer
    subgraph "ASR Library Layer"
        direction TB
        IATClient["IATClient"]:::library
        IATTransports["Transports"]:::library
        ASRTypes["ASR Types"]:::library
    end

    %% AI Library Layer
    subgraph "AI Library Layer"
        direction TB
        OpenAICompat["openaiCompatClient"]:::library
        X1Chat["x1Chat"]:::library
    end

    %% External Services
    subgraph "External Services"
        direction TB
        IATService["iFlytek IAT Service"]:::external
        X1Service["Starfire X1 AI Model"]:::external
    end

    %% Data Flows
    VoiceModal -->|audioBase64| ASR
    ASR -->|invoke| IATClient
    IATClient -->|WebSocket/HTTP| IATService
    IATService -->|transcript| ASR
    ASR -->|transcript| VoiceModal

    IdeaModal -->|text| OPT
    OPT -->|invoke| OpenAICompat
    OpenAICompat -->|chat API| X1Service
    X1Service -->|optimizedText| OPT
    OPT -->|optimizedText| IdeaModal

    IdeaModal -->|read/write| IDB
    VoiceModal -->|read/write| IDB

    %% Click Events - Browser Components
    click Layout "https://github.com/kaminono/echocast-workshop/blob/main/src/app/layout.tsx"
    click GlobalCSS "https://github.com/kaminono/echocast-workshop/blob/main/src/app/globals.css"
    click Home "https://github.com/kaminono/echocast-workshop/blob/main/src/app/page.tsx"
    click IdeasPage "https://github.com/kaminono/echocast-workshop/blob/main/src/app/ideas/page.tsx"
    click DraftsPage "https://github.com/kaminono/echocast-workshop/blob/main/src/app/drafts/page.tsx"
    click TimelinePage "https://github.com/kaminono/echocast-workshop/blob/main/src/app/timeline/page.tsx"
    click Container "https://github.com/kaminono/echocast-workshop/blob/main/src/components/Container.tsx"
    click TopNav "https://github.com/kaminono/echocast-workshop/blob/main/src/components/TopNav.tsx"
    click IdeaModal "https://github.com/kaminono/echocast-workshop/blob/main/src/components/ideas/IdeaCreateModal.tsx"
    click VoiceModal "https://github.com/kaminono/echocast-workshop/blob/main/src/components/ideas/IdeaVoiceModal.tsx"
    click SourceFilter "https://github.com/kaminono/echocast-workshop/blob/main/src/components/ideas/SourceFilter.tsx"
    click IDB "https://github.com/kaminono/echocast-workshop/blob/main/src/lib/indexeddb.ts"

    %% Click Events - API Routes
    click ASR "https://github.com/kaminono/echocast-workshop/blob/main/src/app/api/asr/recognize/route.ts"
    click OPT "https://github.com/kaminono/echocast-workshop/blob/main/src/app/api/ideas/optimize/route.ts"

    %% Click Events - ASR Library
    click IATClient "https://github.com/kaminono/echocast-workshop/blob/main/src/lib/asr/iatClient.ts"
    click IATTransports "https://github.com/kaminono/echocast-workshop/blob/main/src/lib/asr/iatTransport.ts"
    click ASRTypes "https://github.com/kaminono/echocast-workshop/blob/main/src/lib/asr/types.ts"
    click IATTransportBrowser "https://github.com/kaminono/echocast-workshop/blob/main/src/lib/asr/iatTransport.browser.ts"
    click IATTransportFixed "https://github.com/kaminono/echocast-workshop/blob/main/src/lib/asr/iatTransport.fixed.ts"

    %% Click Events - AI Library
    click OpenAICompat "https://github.com/kaminono/echocast-workshop/blob/main/src/lib/ai/openaiCompatClient.ts"
    click X1Chat "https://github.com/kaminono/echocast-workshop/blob/main/src/lib/ai/x1Chat.ts"

    %% Styling
    classDef frontend fill:#C3DDF9,stroke:#0366d6,color:#024c9c;
    classDef api fill:#FFE3B3,stroke:#D9822B,color:#5E370E;
    classDef storage fill:#E2F0CB,stroke:#6B8E23,color:#4B6000;
    classDef library fill:#DAD2E0,stroke:#6B5B95,color:#3F2F48;
    classDef external fill:#F0D9FF,stroke:#9B30FF,color:#5D005D;
```
