# memochou1993/gpt-ai-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/memochou1993/gpt-ai-assistant
- Repository: https://github.com/memochou1993/gpt-ai-assistant

## Overview

##### Project type and purpose
- This is a Node.js-based serverless chat-bot application (“GPT AI Assistant”) that bridges the LINE Messaging API with the OpenAI API (and optionally SerpAPI) to let end users chat with an AI assistant over LINE.
- It’s delivered as a Docker/Vercel function with webhook endpoints, middleware for signature validation, business logic layers (commands, handlers, actions), and integration with external AI services.

##### File structure
- Top level: Dockerfile, docker-compose.yaml, vercel.json, .env.example, config files, CI/config templates.
- “api/index.js”: the HTTP entry point (receives LINE webhook callbacks).
- “middleware/”: request-validation layer (LINE signature validator).
- “app/”: core application with layered subdirectories:
- commands/ – Command objects implementing the “Command” pattern (e.g., analyze-*, bot-*, sum-*, sys-*).
- actions/ – Domain/business-rule implementations (action.js, message.js).
- models/ – Domain entities (Bot, Event, Source).
- history/ – Message history persistence logic.
- prompt/ – Prompt-building utilities.
- repository/ – Data-access layer for ‘Source’ entities.
- messages/ – Message-object builders (template, text, image).
- context.js – Request context builder.
- index.js – Bootstrapper for wiring commands, handlers, services.
- “services/”: external API clients (OpenAI, Line, SerpAPI, Vercel).
- “storage/”: low-level persistence module (e.g. key-value store or file).
- “utils/”: helper functions (fetch-, generate-, validate-, reply-).
- “config/”, “constants/”, “locales/”: configuration, command constants, i18n.
- “tests/”: unit tests per handler/command.

##### README for additional insights
- Confirms use of OpenAI models (gpt-3.5, gpt-4, gpt-4o, Whisper) and support for LINE audio.
- Mentions deployment via Vercel and Docker for local development.

##### Main components & their interactions
a. External Actors & Services:
- End User (LINE mobile app)
- LINE Messaging API (webhook sender & reply receiver)
- OpenAI API (chat/completion, image, transcription)
- SerpAPI (optional web search)
- Vercel Runtime / Docker container (hosting)
b. Core Application Layers:
- API Gateway (api/index.js)
- Middleware (validate signature)
- Routing Layer (handler selection based on webhook event)
- Command Layer (instantiates and executes Command objects)
- Action Layer (business rules, prompt building, event logging)
- Repository Layer (source and history persistence)
- Service Clients (OpenAI, LINE, SerpAPI, Vercel)
- Utilities & Config (helpers, environment, constants, locales)

##### Architectural patterns & principles
- Layered (onion) architecture separating transport, application, domain, and infrastructure.
- Command pattern for encapsulating each chat operation.
- Repository pattern for data access.
- Middleware pipeline for request validation.
- Dependency injection via central bootstrap (app/index.js).
- Single Responsibility principle: handlers only route, commands only orchestrate, actions only implement business logic.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actors
    EU["End User\n(LINE App)"]:::external
    LINE_API["LINE Messaging API"]:::external

    EU -->|sends message via LINE| LINE_API
    LINE_API -->|webhook POST| API_GATEWAY

    subgraph "API Gateway"  
        direction TB
        API_GATEWAY["api/index.js"]:::api
        click API_GATEWAY "https://github.com/memochou1993/gpt-ai-assistant/blob/main/api/index.js"
    end

    %% Middleware Layer
    subgraph "Middleware Layer"  
        direction TB
        MW_REG["middleware/index.js"]:::api
        MW_SIG["validate-line-signature.js"]:::api
        click MW_REG "https://github.com/memochou1993/gpt-ai-assistant/blob/main/middleware/index.js"
        click MW_SIG "https://github.com/memochou1993/gpt-ai-assistant/blob/main/middleware/validate-line-signature.js"
    end

    API_GATEWAY ---> MW_REG
    MW_REG ---> MW_SIG
    MW_SIG ---> ROUTING

    %% Application Core
    subgraph "Application Core"  
        direction TB
        BOOT["app/index.js\n(bootstrapper)"]:::appLogic
        APP_ENTRY["app/app.js"]:::appLogic
        CTX["app/context.js"]:::appLogic
        click BOOT "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/index.js"
        click APP_ENTRY "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/app.js"
        click CTX "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/context.js"
    end

    MW_SIG ---> BOOT
    BOOT ---> APP_ENTRY
    APP_ENTRY ---> CTX
    CTX ---> ROUTING

    %% Routing Layer
    subgraph "Routing Layer"  
        direction TB
        HANDLERS["app/handlers/index.js\n+ handlers/*"]:::appLogic
        click HANDLERS "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/handlers/index.js"
    end

    CTX ---> HANDLERS
    HANDLERS ---> COMMANDS

    %% Command Layer
    subgraph "Command Layer"  
        direction TB
        CMD_INDEX["app/commands/index.js\n+ commands/*.js"]:::appLogic
        CMD_BASE["app/commands/command.js"]:::appLogic
        click CMD_INDEX "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/commands/index.js"
        click CMD_BASE "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/commands/command.js"
    end

    HANDLERS -- internal call --> CMD_INDEX
    CMD_INDEX -- uses --> CMD_BASE
    CMD_INDEX ---> ACTIONS

    %% Action Layer
    subgraph "Action Layer"  
        direction TB
        ACT_INDEX["app/actions/index.js"]:::appLogic
        ACT_BASE["app/actions/action.js"]:::appLogic
        ACT_MSG["app/actions/message.js"]:::appLogic
        click ACT_INDEX "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/actions/index.js"
        click ACT_BASE "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/actions/action.js"
        click ACT_MSG "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/actions/message.js"
    end

    CMD_INDEX -- orchestrates --> ACT_INDEX
    ACT_INDEX ---> DOMAIN

    %% Domain Layer
    subgraph "Domain Layer"  
        direction TB
        MODELS["app/models/index.js\n+ models/*.js"]:::domain
        click MODELS "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/models/index.js"
    end

    ACT_INDEX ---> MODELS
    MODELS ---> PROMPT

    %% Prompt Utilities
    subgraph "Prompt Utilities"  
        direction TB
        PROMPT_IDX["app/prompt/index.js"]:::appLogic
        PROMPT_P["app/prompt/prompt.js"]:::appLogic
        PROMPT_M["app/prompt/message.js"]:::appLogic
        click PROMPT_IDX "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/prompt/index.js"
        click PROMPT_P "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/prompt/prompt.js"
        click PROMPT_M "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/prompt/message.js"
    end

    MODELS ---> PROMPT_IDX
    PROMPT_IDX ---> MSG_BUILD

    %% Message Builders
    subgraph "Message Builders"  
        direction TB
        MSG_IDX["app/messages/index.js"]:::appLogic
        MSG_ALL["app/messages/*.js"]:::appLogic
        click MSG_IDX "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/messages/index.js"
    end

    PROMPT_IDX ---> MSG_IDX
    MSG_IDX ---> REPOSITORY

    %% Repository Layer
    subgraph "Repository Layer"  
        direction TB
        HISTORY["app/history/index.js\napp/history/history.js\napp/history/message.js"]:::infra
        SOURCE["app/repository/index.js\napp/repository/source.js"]:::infra
        click HISTORY "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/history/index.js"
        click SOURCE "https://github.com/memochou1993/gpt-ai-assistant/blob/main/app/repository/index.js"
    end

    MSG_IDX ---> HISTORY
    MSG_IDX ---> SOURCE
    HISTORY ---> SERVICES
    SOURCE ---> SERVICES

    %% Service Clients
    subgraph "Service Clients"  
        direction TB
        LINE_CL["services/line.js"]:::infra
        OPENAI_CL["services/openai.js"]:::infra
        SERP_CL["services/serpapi.js"]:::infra
        VERCEL_CL["services/vercel.js"]:::infra
        SVC_UTIL["services/utils/index.js"]:::infra
        click LINE_CL "https://github.com/memochou1993/gpt-ai-assistant/blob/main/services/line.js"
        click OPENAI_CL "https://github.com/memochou1993/gpt-ai-assistant/blob/main/services/openai.js"
        click SERP_CL "https://github.com/memochou1993/gpt-ai-assistant/blob/main/services/serpapi.js"
        click VERCEL_CL "https://github.com/memochou1993/gpt-ai-assistant/blob/main/services/vercel.js"
        click SVC_UTIL "https://github.com/memochou1993/gpt-ai-assistant/blob/main/services/utils/index.js"
    end

    HISTORY -- queries --> STORAGE
    SOURCE -- queries --> STORAGE
    SERVICES_BUCKET[SVC_UTIL] --- OPENAI_CL
    SERVICES_BUCKET --- SERP_CL
    SERVICES_BUCKET --- LINE_CL
    SERVICES_BUCKET --- VERCEL_CL

    SERVICES_BUCKET -->|calls| OPENAI_CL
    SERVICES_BUCKET -->|calls| SERP_CL
    SERVICES_BUCKET -->|calls| LINE_CL

    %% Storage Layer
    subgraph "Storage Layer"  
        direction TB
        STORAGE["storage/index.js"]:::storage
        click STORAGE "https://github.com/memochou1993/gpt-ai-assistant/blob/main/storage/index.js"
    end

    %% Utilities & Config
    subgraph "Utilities & Config"  
        direction TB
        UTILS["utils/index.js\n+ utils/*"]:::infra
        CONFIG["config/index.js"]:::infra
        CONSTS["constants/command.js\nconstants/mock.js"]:::infra
        LOCALES["locales/index.js\nlocales/en.js\nlocales/ja.js\nlocales/zh.js"]:::infra
        click UTILS "https://github.com/memochou1993/gpt-ai-assistant/blob/main/utils/index.js"
        click CONFIG "https://github.com/memochou1993/gpt-ai-assistant/blob/main/config/index.js"
    end

    %% Host & Deployment
    subgraph "Deployment"  
        direction TB
        DOCKER["Dockerfile\ndocker-compose.yaml"]:::infra
        VERCEL_CFG["vercel.json"]:::infra
        click DOCKER "https://github.com/memochou1993/gpt-ai-assistant/tree/main/Dockerfile"
        click VERCEL_CFG "https://github.com/memochou1993/gpt-ai-assistant/blob/main/vercel.json"
    end

    STORAGE -->|persists| HISTORY
    STORAGE -->|persists| SOURCE

    %% Response Flow
    OPENAI_CL -->|response| ACT_INDEX
    ACT_INDEX -->|builds reply| MSG_BUILD
    MSG_BUILD -->|sends| LINE_CL
    LINE_CL -->|HTTP POST reply| LINE_API

    %% Classes
    classDef external fill:#f2f2f2,stroke:#888,stroke-dasharray: 5 5;
    classDef api fill:#bbdefb,stroke:#1e88e5;
    classDef appLogic fill:#c8e6c9,stroke:#388e3c;
    classDef domain fill:#fff9c4,stroke:#fbc02d;
    classDef infra fill:#ffe0b2,stroke:#f57c00;
    classDef storage fill:#d1c4e9,stroke:#7e57c2;
```
