How supthunder/stoki works
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.