# supthunder/stoki architecture

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

- Interactive diagram: https://gitdiagram.com/supthunder/stoki
- Repository: https://github.com/supthunder/stoki

## Overview

##### Main Components
- Frontend – Built using Next.js with dedicated pages (e.g., login, test, portfolio, comparison) and React components found in the “app” and “components” directories. This includes UI elements like modals, forms, and navigation components.
- Backend API – All API endpoints live under the “app/api” directory. They cover functionality such as authentication (login, verify), portfolio operations (add, delete, edit, performance), crypto and stocks data (batch prices, historical, search), and administrative/debug operations.
- Data Persistence and Cache – The system uses a PostgreSQL database (configured via the DATABASE_URL secret) and Redis caching (via REDIS_URL) to store portfolio data, user information, and possibly intermediate market data.
- External Services – The application fetches stock data (from Yahoo Finance, as indicated in the README) and may rely on third-party data providers.
- GitHub Actions Workflows – Found under “.github/workflows”, these workflows automatically trigger during market hours (using the provided cron expression) to fetch updated prices, update databases and caches, and manage portfolio data.
- Utility & Scripts – The “lib” directory provides helpers (e.g., for auth, cache, crypto API calls, DB interactions), while the “scripts” folder contains database initialization, data seeding, and update scripts (like updating portfolios and historical data).

##### Relationships and Interactions
- User Interaction: The client (browser) accesses the Next.js frontend pages, which then interact with the backend API endpoints.
- Frontend-API: UI components call RESTful API routes (all found under app/api) for key actions like logging in, managing portfolios, and displaying market data.
- API-Data Storage: Backend API handlers perform CRUD operations against the PostgreSQL database and use Redis for caching frequently accessed or computed results.
- Scheduled Processes: GitHub Actions workflows (triggered hourly during market hours) run scripts that retrieve updated stock prices from external APIs (e.g., Yahoo Finance), update the database and refresh cache states.
- Utility Libraries: Common utilities and helper functions (in “lib”) streamline interactions between API routes, external services, and persistent storage.
- Development/Debug: Additional endpoints and scripts (in app/api/debug and scripts/*) provide data validation, system status checks, and test seeding of data.

##### Architectural Patterns and Design Principles
- Separation of Concerns: There is a clear logical separation between client-side presentation, server-side API handling, and background processing via workflows and scripts.
- API-First Approach: With a comprehensive “app/api” directory, the system leverages RESTful endpoints to encapsulate business logic.
- Scheduled and Event-Driven Processing: GitHub Actions workflows orchestrate periodic tasks (data refresh and portfolio updates) following a cron schedule.
- Modular Design: The use of a “lib” directory, component-based UI, and scripts reinforces modularity and reusability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        Pages("Pages (app)"):::frontend
        UI("UI Components (components)"):::frontend
    end

    %% Backend API Layer
    subgraph "Backend API"
        API("API Endpoints (app/api)"):::backend
    end

    %% Utilities & Scripts Layer
    subgraph "Utilities"
        UTIL("Utility & Helpers (lib)"):::utility
        SCRIPTS("Data Scripts (scripts)"):::scripts
    end

    %% Data Persistence Layer
    subgraph "Data Stores"
        DB("PostgreSQL Database"):::infra
        CACHE("Redis Cache"):::infra
    end

    %% CI/CD and External Services Layer
    subgraph "CI & External"
        CI("GitHub Actions Workflows (.github/workflows)"):::ci
        EXT("External Data Provider (Yahoo Finance)"):::external
    end

    %% Connections between layers
    Pages -->|"calls"| API
    UI -->|"calls"| API

    API -->|"CRUD"| DB
    API -->|"cache_update"| CACHE
    API -->|"util_calls"| UTIL
    UTIL -->|"helper_calls"| SCRIPTS

    CI -->|"schedule_updates"| SCRIPTS
    SCRIPTS -->|"update_data"| DB
    SCRIPTS -->|"refresh_cache"| CACHE

    EXT -->|"fetch_data"| CI

    %% Styles
    classDef frontend fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef infra fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef external fill:#F0F4C3,stroke:#827717,stroke-width:2px;
    classDef ci fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef utility fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef scripts fill:#FFE0B2,stroke:#E64A19,stroke-width:2px;

    %% Click Events
    click Pages "https://github.com/supthunder/stoki/tree/main/app"
    click UI "https://github.com/supthunder/stoki/tree/main/components"
    click API "https://github.com/supthunder/stoki/tree/main/app/api"
    click CI "https://github.com/supthunder/stoki/tree/main/.github/workflows"
    click UTIL "https://github.com/supthunder/stoki/tree/main/lib"
    click SCRIPTS "https://github.com/supthunder/stoki/tree/main/scripts"
```
