# bianbianzhu/openai-function-calling architecture

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

- Interactive diagram: https://gitdiagram.com/bianbianzhu/openai-function-calling
- Repository: https://github.com/bianbianzhu/openai-function-calling

## Overview

##### Project type and purpose
- This is a Node.js/TypeScript backend “agent” application that uses OpenAI’s Function Calling API to provide a chat-style interface for exploring and booking farm activities.
- There is no browser-based UI—users drive it via a CLI or embedding in another service.

##### Top-level view of the file structure
- src/index.ts – the application entry point, orchestrates user input, chat flow, and output
- src/scripts/generate-function-files.js – generates TypeScript function stubs from the function-description metadata
- src/services – “service layer” containing:
– openai.ts: wrapper around OpenAI API calls
– chat.ts: coordinates chat completion requests, handles function call responses
– prompts.ts & user-prompt-interface.ts: build and normalize messages/prompts
– function-descriptions*.ts: metadata definitions for each callable function
– functions/*: actual implementations of each function (get_farms, book_activity, etc.)
- src/utils – shared helper modules and tests (chat-utils, common-utils, type-utils)
- Config files – package.json, tsconfig.json, jest.config.ts

##### Main components
a. User Interface (CLI or calling code)
b. Application Orchestrator (src/index.ts)
c. Chat Service (src/services/chat.ts)
d. OpenAI API Client (src/services/openai.ts)
e. Function Definition Registry (function-descriptions*.ts)
f. Function Executors (src/services/functions/*)
g. Utility Library (src/utils)
h. Code-gen Script (src/scripts/generate-function-files.js)

##### Relationships and data flow
1. User sends input → index.ts
2. index.ts invokes Chat Service → chat.ts
3. Chat Service constructs a messages array via Prompt & User-Prompt modules
4. Chat Service calls OpenAI API Client → openai.ts
5. OpenAI returns either a normal chat response or a Function Call directive
6. Chat Service routes function calls to the appropriate Function Executor
7. Function Executor runs business logic (e.g., fetch farms, book activity) → returns result
8. Chat Service packages the function result into a follow-up chat message → returns to index.ts → output to user

##### Architectural patterns and principles
- Layered separation (orchestrator → service → domain/function → utils)
- Single responsibility for each module (each function file implements exactly one API function)
- Metadata-driven generation: function definitions drive both chat prompts and stub generation
- Open/Closed for new functions–you add enums, descriptions, stubs, and handlers without touching core chat flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    User["CLI or Embedding Service"]:::external
    OpenAIAPI["OpenAI API"]:::external

    %% Service Layer
    subgraph "Service Layer"
        Orchestrator["index.ts"]:::service
        ChatService["chat.ts"]:::service
        OpenAIClient["openai.ts"]:::service
        Prompts["prompts.ts"]:::service
        UserPrompt["user-prompt-interface.ts"]:::service
        FuncRegistry1["function-descriptions.ts"]:::service
        FuncRegistry2["function-descriptions-flight-assistant.ts"]:::service
    end

    %% Domain/Function Layer
    subgraph "Domain/Function Layer"
        getFarms["get_farms.ts"]:::domain
        getActivities["get_activities_per_farm.ts"]:::domain
        bookActivity["book_activity.ts"]:::domain
        fileComplaint["file_complaint.ts"]:::domain
        getFlightInfo["flight-assistant/get_flight_info.ts"]:::domain
        bookFlight["flight-assistant/book_flight.ts"]:::domain
        functionsIndex["functions/index.ts"]:::domain
    end

    %% Utilities & Scripts
    subgraph "Utilities & Scripts"
        CodeGen["generate-function-files.js"]:::util
        chatUtils["chat-utils.ts"]:::util
        chatUtilsTest["chat-utils.test.ts"]:::util
        commonUtils["common-utils.ts"]:::util
        typeUtils["type-utils.ts"]:::util
    end

    %% Data Flow
    User -->|"input"| Orchestrator
    Orchestrator -->|"startChat()"| ChatService
    ChatService -->|"build messages"| Prompts
    ChatService -->|"normalize user prompt"| UserPrompt
    ChatService -->|"load function metadata"| FuncRegistry1
    ChatService -->|"load function metadata"| FuncRegistry2
    ChatService -->|"createCompletion()"| OpenAIClient
    OpenAIClient -->|"HTTP Request"| OpenAIAPI
    OpenAIAPI -->|"response"| OpenAIClient
    OpenAIClient -->|"return to ChatService"| ChatService
    ChatService -->|"invoke get_farms() etc"| getFarms
    ChatService -->|"invoke get_activities_per_farm() etc"| getActivities
    ChatService -->|"invoke book_activity() etc"| bookActivity
    ChatService -->|"invoke file_complaint() etc"| fileComplaint
    ChatService -->|"invoke get_flight_info() etc"| getFlightInfo
    ChatService -->|"invoke book_flight() etc"| bookFlight
    getFarms -->|"result"| ChatService
    getActivities -->|"result"| ChatService
    bookActivity -->|"result"| ChatService
    fileComplaint -->|"result"| ChatService
    getFlightInfo -->|"result"| ChatService
    bookFlight -->|"result"| ChatService
    ChatService -->|"return message"| Orchestrator
    Orchestrator -->|"output"| User

    %% Click Events
    click Orchestrator "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/index.ts"
    click CodeGen "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/scripts/generate-function-files.js"
    click ChatService "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/chat.ts"
    click OpenAIClient "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/openai.ts"
    click Prompts "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/prompts.ts"
    click UserPrompt "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/user-prompt-interface.ts"
    click FuncRegistry1 "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/function-descriptions.ts"
    click FuncRegistry2 "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/function-descriptions-flight-assistant.ts"
    click getFarms "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/functions/get_farms.ts"
    click getActivities "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/functions/get_activities_per_farm.ts"
    click bookActivity "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/functions/book_activity.ts"
    click fileComplaint "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/functions/file_complaint.ts"
    click getFlightInfo "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/functions/flight-assistant/get_flight_info.ts"
    click bookFlight "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/functions/flight-assistant/book_flight.ts"
    click functionsIndex "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/services/functions/index.ts"
    click chatUtils "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/utils/chat-utils.ts"
    click chatUtilsTest "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/utils/chat-utils.test.ts"
    click commonUtils "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/utils/common-utils.ts"
    click typeUtils "https://github.com/bianbianzhu/openai-function-calling/blob/main/src/utils/type-utils.ts"

    %% Styles
    classDef external fill:#e0f7e9,stroke:#2e7d32
    classDef service fill:#bbdefb,stroke:#1565c0
    classDef domain fill:#ffe0b2,stroke:#ef6c00
    classDef util fill:#eeeeee,stroke:#616161
```
