# furkancanzirek/bist-etf-tracking architecture

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

- Interactive diagram: https://gitdiagram.com/furkancanzirek/bist-etf-tracking
- Repository: https://github.com/furkancanzirek/bist-etf-tracking

## Overview

##### Main Components
- Frontend Client: Represented by the Next.js “app” folder containing layout.js, page.js, and dynamic fund pages. This includes UI components (in the “components” folder, with Shadcn UI elements) and hooks for better responsiveness.
- API Endpoints: Inside “app/api”, there are dedicated endpoints (for “etf” and “scrape”) which expose server actions. These endpoints are responsible for processing client requests, interacting with backend services, and triggering scraping functions.
- Business Logic / Service Layer: Distributed in “actions” (e.g., fetchFundChange.js), “services” (for ETF change retrieval), and utility functions under “lib”. These modules encapsulate the core data processing and scraping logic.
- Data Layer: The presence of schema.sql, db.json, and the README’s reference to Cloudflare D1 point to a dedicated database layer (Cloudflare D1). This layer manages persistent storage for funds, stocks, and related scraped data.
- External Services Integration: Cloudflare Workers are evident from “wrangler.toml.example” and “src/index.ts”. This service component likely handles additional tasks such as initiating scraping or offloading some workload to the edge.
- Deployment/Configuration: Files such as next.config.mjs, postcss.config.js, tailwind.config.js, and package.json indicate build and deployment configurations, with Cloudflare Pages handling the hosting environment.

##### Relationships and Interactions
- User requests go to the Frontend Client (built using Next.js) which interacts with the API endpoints to fetch updated fund/ETF changes.
- API routes (in “app/api/”) call on business logic modules in “actions”, “services”, and “lib” to retrieve, process, or scrape data.
- Data persistence is managed through Cloudflare D1; the API endpoints and server actions write to or query the database (using schema defined in schema.sql).
- Cloudflare Workers (with entry point in “src/index.ts”) may be used to perform asynchronous or periodic scraping tasks using functions from “lib/scrape*.js” and leveraging Cheerio for HTML parsing.
- UI components (in “components” and “components/ui”) are used to render dynamic data on fund pages and incorporate reusable UI patterns.

##### Architectural Patterns and Key Technologies
- Separation of Concerns: The project clearly segments the presentation layer (Next.js pages and UI components), business logic (actions, services, lib), and data layer (Cloudflare D1).
- Serverless and Edge Functions: Integration with Cloudflare Workers showcases the use of edge computing to handle intensive tasks such as data scraping.
- API-Driven Communication: The Next.js Server Actions and API endpoints form a RESTful (or action-based) interaction layer between the client and backend logic.
- Modern Frontend Stack: Utilization of Next.js 14, Shadcn UI, and Tailwind CSS (configured via tailwind.config.js) helps maintain a responsive design.

##### Detailed Elements
- Clear labels for each component, ensuring that both high-level blocks (Frontend, API/Business Logic, Cloudflare services) and sub-components (e.g., specific API endpoints or utility modules) are visible.
- Request flow: From the client (Next.js UI) → API Endpoints → Business Logic → Data Storage.
- Asynchronous updates: From Cloudflare Workers → Database (Cloudflare D1) and possibly back to API endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    User["User"]:::external

    %% Frontend Client
    subgraph "Frontend Client"
        NP1["Home Page (app/page.js)"]:::frontend
        NP2["Fund Page (app/funds/[slug]/page.jsx)"]:::frontend
        NP3["Layout (app/layout.js)"]:::frontend
        UIC["UI Components (components)"]:::frontend
        UIE["UI Elements (components/ui)"]:::frontend
    end

    %% API Endpoints
    subgraph "API Endpoints"
        API1["ETF API (app/api/etf/route.js)"]:::api
        API2["Scrape API (app/api/scrape/route.js)"]:::api
    end

    %% Business Logic / Service Layer
    subgraph "Business Logic/Service Layer"
        AL["Actions: fetchFundChange (actions/fetchFundChange.js)"]:::business
        SV["Services: getETFChange (services/getETFChange.js)"]:::business
        LIB1["Lib: getFundCodes (lib/getFundCodes.js)"]:::business
        LIB2["Lib: scrape (lib/scrape.js)"]:::business
        LIB3["Lib: scrapeEtf (lib/scrapeEtf.js)"]:::business
        LIB4["Lib: scrapeEtfs (lib/scrapeEtfs.js)"]:::business
        LIB5["Lib: utils (lib/utils.js)"]:::business
    end

    %% Data Layer (Cloudflare D1)
    subgraph "Database Layer (Cloudflare D1)"
        DB1["Schema (schema.sql)"]:::database
        DB2["Data (db.json)"]:::database
    end

    %% External Services Integration (Cloudflare Workers)
    subgraph "External Services"
        CFW1["Worker Entry (src/index.ts)"]:::external
        CFW2["Worker Config (wrangler.toml.example)"]:::external
    end

    %% Deployment / Configuration
    subgraph "Deployment/Configuration"
        DEP1["Build & Config Files (next.config.mjs, postcss.config.js, tailwind.config.js, package.json)"]:::deployment
    end

    %% Connections - User interacting with Frontend
    User -->|"initiates request"| NP1
    User -->|"navigates"| NP2

    %% Frontend calls API Endpoints
    NP1 -->|"calls"| API1
    NP2 -->|"calls"| API1
    NP3 -->|"provides layout for"| NP1
    UIC -->|"renders UI"| NP1
    UIE -->|"renders UI"| NP2

    %% API Endpoints invoke Business Logic
    API1 -->|"invokes"| SV
    API2 -->|"triggers"| AL
    API2 -->|"triggers"| LIB2
    API2 -->|"triggers"| LIB3
    API2 -->|"triggers"| LIB4

    %% Business Logic interactions
    AL -->|"uses"| LIB1
    SV -->|"utilizes"| LIB5

    %% Business Logic and Data Layer
    AL -->|"reads/writes"| DB1
    SV -->|"reads/writes"| DB1
    LIB1 -->|"supports"| AL
    LIB2 -->|"processes data"| DB2
    LIB3 -->|"processes data"| DB2
    LIB4 -->|"processes data"| DB2
    LIB5 -->|"assists"| SV

    %% External Services interactions with Business Logic and Data Layer
    CFW1 -->|"triggers scraping"| LIB2
    CFW1 -->|"triggers scraping"| LIB3
    CFW1 -->|"triggers scraping"| LIB4
    CFW1 -->|"updates"| DB1

    %% Deployment influences
    DEP1 -->|"deploys frontend"| NP1
    DEP1 -->|"deploys API"| API1

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef business fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef database fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef deployment fill:#FFB6C1,stroke:#333,stroke-width:2px;

    %% Click Events for Frontend UI
    click NP1 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/app/page.js"
    click NP2 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/app/funds/[slug]/page.jsx"
    click NP3 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/app/layout.js"
    click UIC "https://github.com/furkancanzirek/bist-etf-tracking/tree/main/components"
    click UIE "https://github.com/furkancanzirek/bist-etf-tracking/tree/main/components/ui"

    %% Click Events for API Endpoints
    click API1 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/app/api/etf/route.js"
    click API2 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/app/api/scrape/route.js"

    %% Click Events for Business Logic / Service Layer
    click AL "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/actions/fetchFundChange.js"
    click SV "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/services/getETFChange.js"
    click LIB1 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/lib/getFundCodes.js"
    click LIB2 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/lib/scrape.js"
    click LIB3 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/lib/scrapeEtf.js"
    click LIB4 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/lib/scrapeEtfs.js"
    click LIB5 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/lib/utils.js"

    %% Click Events for Data Layer
    click DB1 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/schema.sql"
    click DB2 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/db.json"

    %% Click Events for External Services Integration
    click CFW1 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/src/index.ts"
    click CFW2 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/wrangler.toml.example"

    %% Click Event for Deployment / Configuration
    click DEP1 "https://github.com/furkancanzirek/bist-etf-tracking/blob/main/next.config.mjs"
```
