# cpj-n/stocksnip architecture

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

- Interactive diagram: https://gitdiagram.com/cpj-n/stocksnip
- Repository: https://github.com/cpj-n/stocksnip

## Overview

##### Project Type and Purpose
- Type: Full-stack web application built with Next.js 13 (App Router) and TypeScript.
- Purpose: Let users enter a stock ticker, fetch the latest stock data and news via Alpha Vantage, generate an AI summary using Together Compute, and display results in a responsive React UI.

##### File Structure
- Top-level config files:
– next.config.ts, tsconfig.json, tailwind.config.ts → Next.js, TypeScript, Tailwind setup.
– .example.env → holds API keys for Alpha Vantage and Together Compute.
- Public assets: public/img/stocksnip.png.
- Application code (src/app):
– layout.tsx, globals.css → site‐wide layout and styles.
– page.tsx → homepage UI.
– /pricing/page.tsx → pricing information.
- API routes (src/app/api):
– getStockData/route.ts → calls Alpha Vantage stock‐price endpoint.
– getStockNews/route.ts → calls Alpha Vantage news endpoint.
– getSummary/route.ts → calls Together Compute for AI summarization.
- UI components (src/components & ui folder) → Shadcn UI building blocks (button, card, chart, etc.).
- Utilities (src/lib/utils.ts) → shared helper functions (e.g., formatting, error handling).

##### README Insights
- Core integrations: Alpha Vantage for data/news; Together Compute for summaries.
- Styling: Tailwind CSS + Shadcn UI.
- Hosting/deployment on Vercel.
- Next.js features: next/font optimization, SSR/SSG, API routes.

a. Main Components
- Client (Browser)
- Next.js Frontend (React Server + Client Components)
- Next.js API Layer (Serverless route handlers)
- External Services:
– Alpha Vantage API
– Together Compute AI API
- Configuration & Hosting
– Environment Variables
– Vercel Platform
b. Relationships & Data Flows
1. User loads page → HTTP(S) GET to Next.js server → React renders page.
2. On ticker search: Frontend issues fetches to `/api/getStockData` and `/api/getStockNews`.
3. API routes forward requests to Alpha Vantage, return JSON to frontend.
4. Frontend stitches data, then POSTs consolidated news to `/api/getSummary`.
5. getSummary route calls Together Compute with news text, returns AI summary.
6. Frontend displays summary in UI.
c. Architectural Patterns & Principles
- Monolithic Next.js app with clearly separated API routes.
- Serverless functions for backend logic (zero-server maintenance).
- Component-based UI with atomic principles (shadcn components).
- CSS utility-first design (Tailwind).
- Environment-driven configuration (API keys via env vars).
d. Key Technologies & Frameworks
- Next.js 13 App Router (server + client components)
- React & TypeScript
- Tailwind CSS & Shadcn UI
- Node.js serverless API routes
- Alpha Vantage REST API
- Together Compute AI API
- Vercel deployment

##### Detail
- Every major route handler and its downstream service call.
- Environment variables feeding into API routes.
- Build/config pipeline (next.config.ts, tailwind.config.ts) as a side note.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    subgraph "Client (Browser)"
        direction TB
        Browser["Web Browser"]:::internal
    end

    %% Next.js Service
    subgraph "Next.js Service"
        direction TB
        subgraph "Frontend (App)"
            direction TB
            Layout["layout.tsx"]:::internal
            Globals["globals.css"]:::internal
            HomePage["page.tsx"]:::internal
            PricingPage["pricing/page.tsx"]:::internal
            subgraph "UI Components"
                direction TB
                Button["Button"]:::internal
                Card["Card"]:::internal
                Chart["Chart"]:::internal
                Input["Input"]:::internal
                Alert["Alert"]:::internal
            end
            subgraph "Common Components"
                direction TB
                Footer["Footer"]:::internal
                LoadingSpinner["LoadingSpinner"]:::internal
            end
            Utils["utils.ts"]:::internal
        end
        subgraph "Backend (Serverless Functions)"
            direction TB
            StockDataAPI["getStockData API Route"]:::internal
            StockNewsAPI["getStockNews API Route"]:::internal
            SummaryAPI["getSummary API Route"]:::internal
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AlphaVantage[("Alpha Vantage API")]:::external
        TogetherCompute[("Together Compute AI API")]:::external
    end

    %% Platform & Config
    subgraph "Platform & Configuration"
        direction TB
        Env[".example.env"]:::platform
        NextConfig["next.config.ts"]:::platform
        TailwindConfig["tailwind.config.ts"]:::platform
        TSConfig["tsconfig.json"]:::platform
        Vercel["Vercel Deployment"]:::platform
    end

    %% Data Flows
    Browser -->|"GET /"| Layout
    Browser -->|"GET /"| HomePage
    Browser -->|"GET /pricing"| PricingPage
    HomePage -->|"fetch /api/getStockData"| StockDataAPI
    HomePage -->|"fetch /api/getStockNews"| StockNewsAPI
    HomePage -->|"POST /api/getSummary"| SummaryAPI

    StockDataAPI -->|"HTTPS/JSON"| AlphaVantage
    StockNewsAPI -->|"HTTPS/JSON"| AlphaVantage
    SummaryAPI -->|"HTTPS/JSON"| TogetherCompute

    Env --> StockDataAPI
    Env --> StockNewsAPI
    Env --> SummaryAPI

    NextConfig --> Layout
    TailwindConfig --> Globals
    TSConfig --> Layout

    Vercel --- NextConfig

    %% Click Events
    click Layout "https://github.com/cpj-n/stocksnip/blob/main/src/app/layout.tsx"
    click Globals "https://github.com/cpj-n/stocksnip/blob/main/src/app/globals.css"
    click HomePage "https://github.com/cpj-n/stocksnip/blob/main/src/app/page.tsx"
    click PricingPage "https://github.com/cpj-n/stocksnip/blob/main/src/app/pricing/page.tsx"
    click StockDataAPI "https://github.com/cpj-n/stocksnip/blob/main/src/app/api/getStockData/route.ts"
    click StockNewsAPI "https://github.com/cpj-n/stocksnip/blob/main/src/app/api/getStockNews/route.ts"
    click SummaryAPI "https://github.com/cpj-n/stocksnip/blob/main/src/app/api/getSummary/route.ts"
    click Button "https://github.com/cpj-n/stocksnip/blob/main/src/components/ui/button.tsx"
    click Card "https://github.com/cpj-n/stocksnip/blob/main/src/components/ui/card.tsx"
    click Chart "https://github.com/cpj-n/stocksnip/blob/main/src/components/ui/chart.tsx"
    click Input "https://github.com/cpj-n/stocksnip/blob/main/src/components/ui/input.tsx"
    click Alert "https://github.com/cpj-n/stocksnip/blob/main/src/components/ui/alert.tsx"
    click Footer "https://github.com/cpj-n/stocksnip/blob/main/src/components/Footer.tsx"
    click LoadingSpinner "https://github.com/cpj-n/stocksnip/blob/main/src/components/LoadingSpinner.tsx"
    click Utils "https://github.com/cpj-n/stocksnip/blob/main/src/lib/utils.ts"
    click Env "https://github.com/cpj-n/stocksnip/blob/main/.example.env"
    click NextConfig "https://github.com/cpj-n/stocksnip/blob/main/next.config.ts"
    click TailwindConfig "https://github.com/cpj-n/stocksnip/blob/main/tailwind.config.ts"
    click TSConfig "https://github.com/cpj-n/stocksnip/blob/main/tsconfig.json"
    click Vercel "https://github.com/cpj-n/stocksnip/tree/main/vercel"
    
    %% Styles
    classDef internal fill:#D0E7FF,stroke:#0366D6,color:#0366D6
    classDef external fill:#E6FFDD,stroke:#28A745,color:#28A745
    classDef platform fill:#F0F0F0,stroke:#666666,color:#666666,line-style:dashed
```
