# atikp/apst_frontend architecture

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

- Interactive diagram: https://gitdiagram.com/atikp/apst_frontend
- Repository: https://github.com/atikp/apst_frontend

## Overview

##### Project Type and Purpose
- This is a frontend-only single-page application (SPA) built with React and Vite.
- Its purpose is to simulate a stock trading environment: it provides UI components for authentication, portfolio management, real‐time charts, news, buy/sell operations, and user rewards.

##### High‐Level Architecture Components
a. Client (Browser)
- Hosts the React/Vite SPA (served via Netlify).
- Renders UI using TailwindCSS for styling, ApexCharts for charts, Framer Motion for animations, React-Toastify for notifications.
b. Firebase Services (Client SDK)
- Firebase Authentication: email/password login.
- Firestore Database: stores user portfolios, transactions, accolades.
c. Express Backend (Deployed on Render)
- Acts as a secure proxy to external stock/data APIs.
- Implements buy/sell logic, portfolio updates (writes to Firestore).
- Protects secret API keys (Alpha Vantage, FMP, Finnhub).
d. External Data Providers
- Alpha Vantage: real-time and historical stock data.
- Financial Modeling Prep (FMP): company profiles.
- Finnhub: news feed and quote WebSocket stream.

##### Relationships and Data Flows
- User interacts with the React SPA in browser.
- SPA ↔ Firebase Auth SDK: handles signup/login, obtains user token.
- SPA ↔ Firestore SDK: reads/writes user portfolio, holdings, transactions, accolades.
- SPA ↔ Express API (via src/utils/api.js): for buy/sell operations and proxying data requests.
- The SPA passes the user’s Firebase token in Authorization headers.
- Express API → External Providers: fetches market data, news, profiles.
- Express API → Firestore (using Firebase Admin SDK): updates user portfolio on buy/sell.

##### Architectural Patterns and Principles
- Clear separation of concerns:
- UI layer (React components under src/components)
- State & Context (src/context/UserContext.jsx)
- Data access layer (src/utils/api.js, firebase.js)
- Reusable custom hooks (src/hooks)
- Proxy pattern: Express API secures secrets and centralizes business logic.
- Componentization: small, focused React components and directories (ChartComponents, SmallerComponents).
- Single source of truth: UserContext handles auth state and shares across app.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client (Browser)" 
        direction TB
        ReactApp["React App (Vite)\n- React, Vite, Tailwind, ApexCharts, Framer Motion, React-Toastify"]:::client

        subgraph "Config & Entry"
            direction TB
            Entry["Entry Point\nsrc/main.jsx"]:::util
            ViteConfig["Vite Config\nvite.config.js"]:::util
            HTML["HTML Template\nindex.html"]:::util
            Styles["Global Styles\nsrc/index.css\nsrc/App.css"]:::util
        end

        subgraph "State & Context"
            direction TB
            UserCtx["UserContext\nsrc/context/UserContext.jsx"]:::client
            AccoladeHook["UseAccolades Hook\nsrc/hooks/UseAccolades.jsx"]:::client
            StreakHook["useLoginStreak Hook\nsrc/hooks/useLoginStreak.jsx"]:::client
        end

        subgraph "Utils"
            direction TB
            FirebaseSetup["Firebase Setup\nfirebase.js"]:::util
            APIUtil["API Proxy Utilities\nsrc/utils/api.js"]:::util
            URLSafe["URL Safety Utility\nsrc/utils/isSafeUrl.js"]:::util
            Sanitize["Sanitization Utility\nsrc/utils/sanitize.js"]:::util
        end

        subgraph "Components"
            direction TB
            ChartComps["ChartComponents Dir"]:::client
            SmallerComps["SmallerComponents Dir"]:::client
        end

        subgraph "Pages"
            direction TB
            Pages["Page-Level Components"]:::client
        end

        ReactApp --> Entry
        ReactApp --> ViteConfig
        ReactApp --> HTML
        ReactApp --> Styles
        ReactApp --> UserCtx
        ReactApp --> APIUtil
        ReactApp --> ChartComps
        ReactApp --> SmallerComps
        ReactApp --> Pages
    end

    %% Firebase Services
    subgraph "Firebase Services" 
        direction TB
        Auth["Firebase Auth SDK"]:::db
        Firestore["Firestore Database"]:::db
    end

    %% Backend Service
    ExpressAPI["Express API (Render)\n- Express.js, Firebase Admin SDK\n- Proxy & Business Logic"]:::backend

    %% External APIs
    subgraph "External Data Providers"
        direction TB
        AlphaV["Alpha Vantage"]:::external
        FMP["Financial Modeling Prep"]:::external
        Finnhub["Finnhub\n(WebSocket)"]:::external
    end

    %% Connections
    ReactApp -->|HTTPS REST| Auth
    ReactApp -->|HTTPS REST| Firestore
    ReactApp -->|HTTPS REST\nAuthorization:Bearer token| ExpressAPI

    ExpressAPI -->|Admin SDK Writes| Firestore
    ExpressAPI -->|HTTPS REST| AlphaV
    ExpressAPI -->|HTTPS REST| FMP
    ExpressAPI -->|WebSocket| Finnhub

    %% Click Events
    click Entry "https://github.com/atikp/apst_frontend/blob/main/src/main.jsx"
    click ViteConfig "https://github.com/atikp/apst_frontend/blob/main/vite.config.js"
    click HTML "https://github.com/atikp/apst_frontend/blob/main/index.html"
    click Styles "https://github.com/atikp/apst_frontend/blob/main/src/index.css"
    click Styles "https://github.com/atikp/apst_frontend/blob/main/src/App.css"
    click FirebaseSetup "https://github.com/atikp/apst_frontend/blob/main/firebase.js"
    click APIUtil "https://github.com/atikp/apst_frontend/blob/main/src/utils/api.js"
    click URLSafe "https://github.com/atikp/apst_frontend/blob/main/src/utils/isSafeUrl.js"
    click Sanitize "https://github.com/atikp/apst_frontend/blob/main/src/utils/sanitize.js"
    click UserCtx "https://github.com/atikp/apst_frontend/blob/main/src/context/UserContext.jsx"
    click AccoladeHook "https://github.com/atikp/apst_frontend/blob/main/src/hooks/UseAccolades.jsx"
    click StreakHook "https://github.com/atikp/apst_frontend/blob/main/src/hooks/useLoginStreak.jsx"
    click ChartComps "https://github.com/atikp/apst_frontend/tree/main/src/components/ChartComponents"
    click SmallerComps "https://github.com/atikp/apst_frontend/tree/main/src/components/SmallerComponents"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef db fill:#DFFFE0,stroke:#28A745,stroke-width:1px
    classDef backend fill:#FFE8CC,stroke:#D97706,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#6B7280,stroke-width:1px
    classDef util fill:#E5E7EB,stroke:#4B5563,stroke-width:1px
```
