# arvinlovegood/go-stock architecture

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

- Interactive diagram: https://gitdiagram.com/arvinlovegood/go-stock
- Repository: https://github.com/arvinlovegood/go-stock

## Overview

##### Project Type and Purpose
- The project is a full-stack desktop application built with a Go backend using Wails to integrate with a modern web-based frontend. The purpose is to provide AI-powered stock analysis for markets such as A-shares, Hong Kong stocks, and US stocks, integrating multiple APIs (e.g., for stock data, AI models, news crawling, etc.) while providing interactive user experiences via NaiveUI / Vue.
- The README stresses integration with various AI models (OpenAI, Ollama, LMStudio, etc.) and emphasizes stock market data and multi-platform support.

##### File Structure
- Top-Level Indicators:
– The project has a clear separation between frontend and backend directories.
– Several build scripts and platform-specific files (e.g., app_darwin.go, app_linux.go, Windows installer scripts) indicate cross-platform build support.
– Presence of a “wails.json” suggests project configuration for the Wails framework.
- Backend Directory:
– Contains multiple subdirectories such as “data” (for different API integrations like alert, crawler, dingding, stock data, etc.), “db” (for database connectivity or persistence), “logger” (for logging functionality), and “models” (defining the data structures).
– The API implementations (e.g., fund_data_api, tushare_data_api) are distinct and each comes with its own test files.
- Frontend Directory:
– Contains Vue components (App.vue, components like about.vue, fund.vue, settings.vue, stock.vue) and a router configuration which is built using Vite.
– The “wailsjs” folder shows that Wails generates JavaScript and TypeScript bindings for Go code, bridging the frontend with backend methods.
- Shared and Infrastructure Elements:
– The main Go files at the root (app.go, main.go) serve as entry points.
– Build and scripts directories contain platform-specific deployment/build scripts.

##### Key Architectural Components
- Frontend Layer:
- Vue.js-based user interface built with NaiveUI, with configuration via Vite.
- Routing and components (for displaying stock data, AI analysis results, settings, etc.).
- Interfaces (wailsjs) to invoke Go backend functions.
- Backend Layer:
- Go business logic implemented via multiple packages:
▪ Data Layer: Different API clients (OpenAI, crawler, Tushare, etc.) for fetching or processing stock and financial data.
▪ Models: Data structures and domain models.
▪ Logger: Logging subsystem.
▪ Database: Data persistence or storage abstraction.
- Platform-specific variations (files like app_darwin.go and app_linux.go) to handle OS-specific functionality.
- Integration & Communication:
- Communication between the frontend and backend through the Wails runtime.
- APIs wrapping external services like OpenAI, Dingding, etc.
- CI/CD and Build Processes:
- GitHub workflows (in .github/workflows) for continuous integration.
- Scripts for building on various platforms (macOS arm/intel, Windows, etc.).

a. Main Components:
- “CI/CD Pipeline” to denote GitHub workflows and build scripts.

b. Relationships and Data Flow:

c. Architectural Patterns & Design Principles:
- Separation of concerns (frontend vs. backend).
- The modular design in the backend: separate directories for data access, logging, and models, which suggests an organized architecture similar to MVC or layered architecture.
- The usage of platform-specific entry points for customized builds is also a notable design choice.

d. Relevant Technologies:
- Frontend: Vue, NaiveUI, Vite.
- Backend: Go, Wails framework, and various third-party APIs (OpenAI, Tushare, etc.).
- Build & CI: GitHub Actions, shell scripts for cross-platform builds, and configuration through wails.json.

- Use clear, descriptive labels for each component (e.g., "Frontend (Vue + NaiveUI)", "Backend Data API (Stock/Tushare/OpenAI)", "Logger", "Database", "Wails Runtime Bridge").

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        FE["Frontend UI (Vue + NaiveUI)"]:::frontend
    end

    subgraph "Wails Bridge"
        WBR["Wails Runtime Bridge"]:::bridge
    end

    subgraph "Backend Layer"
        BL1["Data Layer (API Integrations)"]:::backend
        BL2["Models"]:::backend
        BL3["Logger"]:::backend
        BL4[(Database)]:::database
        BL5["Platform-Specific Adapters"]:::backend
    end

    subgraph "External Services"
        ES["External APIs (OpenAI, Tushare, Dingding, etc)"]:::external
    end

    subgraph "CI/CD Pipeline"
        CI["GitHub Workflows & Build Scripts"]:::cicd
    end

    %% Connections between Frontend and Backend via Wails Bridge
    FE -->|"WailsBindings"| WBR
    WBR -->|"RPC"| BL1
    WBR -->|"RPC"| BL2
    WBR -->|"RPC"| BL3
    WBR -->|"RPC"| BL4
    WBR -->|"RPC"| BL5

    %% Backend internal interactions and external calls
    BL1 -->|"APICalls"| ES
    BL1 -->|"UsesModels"| BL2
    BL1 -->|"LogsTo"| BL3
    BL1 -->|"StoresDataIn"| BL4

    %% Build process connections with CI/CD Pipeline
    CI -->|"BuildsFrontend"| FE
    CI -->|"BuildsBackend"| BL1
    CI -->|"BuildsBackend"| BL2
    CI -->|"BuildsBackend"| BL3
    CI -->|"BuildsBackend"| BL4
    CI -->|"BuildsBackend"| BL5

    %% Click Events for Component Mapping
    click FE "https://github.com/arvinlovegood/go-stock/tree/master/frontend/"
    click WBR "https://github.com/arvinlovegood/go-stock/blob/master/wails.json"
    click BL1 "https://github.com/arvinlovegood/go-stock/tree/master/backend/data/"
    click BL2 "https://github.com/arvinlovegood/go-stock/blob/master/backend/models/models.go"
    click BL3 "https://github.com/arvinlovegood/go-stock/tree/master/backend/logger/"
    click BL4 "https://github.com/arvinlovegood/go-stock/blob/master/backend/db/db.go"
    click BL5 "https://github.com/arvinlovegood/go-stock/blob/master/app_darwin.go"
    click CI "https://github.com/arvinlovegood/go-stock/tree/master/.github/workflows/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef bridge fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef backend fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef database fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef cicd fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
