Update v1.0

Author: MarkHershey

.github/workflows/deploy.yml

@@ -0,0 +1,62 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm run build
+        env:
+          GITHUB_PAGES: true
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './dist'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

App.tsx

@@ -0,0 +1,225 @@
+import React, { useState, useEffect } from "react";
+import { parseJSONData } from "./utils/dataParser";
+import { AccountData, PositionData } from "./types";
+import SummaryCard from "./components/SummaryCard";
+import PositionsTable from "./components/PositionsTable";
+import PortfolioChart from "./components/PortfolioChart";
+import FileDropZone from "./components/FileDropZone";
+import { LayoutDashboard, Trash2, Maximize2, Minimize2 } from "lucide-react";
+
+const APP_NAME = "Alloc";
+const STORAGE_KEY = `${APP_NAME}_json_data`;
+const FULL_WIDTH_STORAGE_KEY = `${APP_NAME}_full_width_preference`;
+
+const App: React.FC = () => {
+    const [account, setAccount] = useState<AccountData | null>(null);
+    const [positions, setPositions] = useState<PositionData[]>([]);
+    const [parseError, setParseError] = useState<string | null>(null);
+    const [isLoadingFromStorage, setIsLoadingFromStorage] = useState(true);
+    const [isFullWidth, setIsFullWidth] = useState<boolean>(false);
+
+    // Load data from localStorage on mount
+    useEffect(() => {
+        const loadFromStorage = () => {
+            try {
+                const storedJSON = localStorage.getItem(STORAGE_KEY);
+
+                if (storedJSON) {
+                    // Try to parse the stored JSON data
+                    const { account, positions } = parseJSONData(storedJSON);
+
+                    if (account && positions && positions.length > 0) {
+                        setAccount(account);
+                        setPositions(positions);
+                    } else {
+                        // Stored data is invalid, clear it
+                        localStorage.removeItem(STORAGE_KEY);
+                    }
+                }
+
+                // Load full-width preference
+                const fullWidthPreference = localStorage.getItem(
+                    FULL_WIDTH_STORAGE_KEY
+                );
+                if (fullWidthPreference !== null) {
+                    setIsFullWidth(fullWidthPreference === "true");
+                }
+            } catch (e) {
+                console.error("Failed to load data from localStorage", e);
+                // Clear corrupted data
+                localStorage.removeItem(STORAGE_KEY);
+            } finally {
+                setIsLoadingFromStorage(false);
+            }
+        };
+
+        loadFromStorage();
+    }, []);
+
+    const handleFileLoaded = (jsonContent: string) => {
+        try {
+            setParseError(null);
+
+            const { account, positions } = parseJSONData(jsonContent);
+
+            if (!account) {
+                throw new Error(
+                    "Failed to parse account data. Please check the file format."
+                );
+            }
+
+            if (!positions || positions.length === 0) {
+                throw new Error(
+                    "Failed to parse positions data or file is empty. Please check the file format."
+                );
+            }
+
+            // Save to localStorage
+            localStorage.setItem(STORAGE_KEY, jsonContent);
+
+            setAccount(account);
+            setPositions(positions);
+        } catch (e) {
+            const errorMessage =
+                e instanceof Error
+                    ? e.message
+                    : "Failed to parse data. Please check your JSON file.";
+            setParseError(errorMessage);
+            console.error("Failed to parse data", e);
+        }
+    };
+
+    const handleError = (error: string) => {
+        setParseError(error);
+    };
+
+    const handleReset = () => {
+        setAccount(null);
+        setPositions([]);
+        setParseError(null);
+        // Clear localStorage
+        localStorage.removeItem(STORAGE_KEY);
+    };
+
+    const handleToggleFullWidth = () => {
+        const newValue = !isFullWidth;
+        setIsFullWidth(newValue);
+        localStorage.setItem(FULL_WIDTH_STORAGE_KEY, String(newValue));
+    };
+
+    // Show loading state while checking localStorage
+    if (isLoadingFromStorage) {
+        return (
+            <div className="min-h-screen bg-slate-900 flex items-center justify-center">
+                <div className="text-blue-500 animate-pulse text-xl font-semibold">
+                    Loading Portfolio Data...
+                </div>
+            </div>
+        );
+    }
+
+    // Show drag and drop interface if no account data is loaded
+    if (!account) {
+        return (
+            <FileDropZone
+                onFileLoaded={handleFileLoaded}
+                onError={handleError}
+                parseError={parseError}
+            />
+        );
+    }
+
+    // Calculate some aggregate totals that might be missing or useful
+    const totalDailyPL = positions.reduce(
+        (acc, curr) => acc + curr.today_pl_val,
+        0
+    );
+    const totalUnrealizedPL = positions.reduce(
+        (acc, curr) => acc + curr.unrealized_pl,
+        0
+    );
+
+    return (
+        <div className="min-h-screen bg-slate-900 pb-12">
+            {/* Header */}
+            <nav className="bg-slate-800 border-b border-slate-700 sticky top-0 z-50">
+                <div
+                    className={`${
+                        isFullWidth ? "max-w-full" : "max-w-7xl"
+                    } mx-auto px-4 sm:px-6 lg:px-8`}
+                >
+                    <div className="flex justify-between h-16 items-center">
+                        <div className="flex items-center gap-2">
+                            <LayoutDashboard className="h-6 w-6 text-blue-500" />
+                            <span className="font-bold text-xl text-white tracking-tight">
+                                <span className="text-blue-500">Alloc</span>{" "}
+                                Dashboard
+                            </span>
+                        </div>
+                        <div className="flex items-center gap-4 text-sm">
+                            <button
+                                onClick={handleToggleFullWidth}
+                                className="flex items-center gap-2 px-3 py-1.5 text-sm text-slate-400 hover:text-white bg-slate-700/50 hover:bg-slate-700 rounded-lg transition-colors"
+                                title={
+                                    isFullWidth
+                                        ? "Use Constrained Width"
+                                        : "Use Full Width"
+                                }
+                            >
+                                {isFullWidth ? (
+                                    <Minimize2 className="h-4 w-4" />
+                                ) : (
+                                    <Maximize2 className="h-4 w-4" />
+                                )}
+                                <span className="hidden sm:inline">
+                                    {isFullWidth ? "Constrained" : "Full Width"}
+                                </span>
+                            </button>
+                            <button
+                                onClick={handleReset}
+                                className="flex items-center gap-2 px-3 py-1.5 text-sm text-slate-400 hover:text-white bg-slate-700/50 hover:bg-slate-700 rounded-lg transition-colors"
+                                title="Clear Data"
+                            >
+                                <Trash2 className="h-4 w-4" />
+                                <span className="hidden sm:inline">
+                                    Clear Data
+                                </span>
+                            </button>
+                        </div>
+                    </div>
+                </div>
+            </nav>
+
+            <main
+                className={`${
+                    isFullWidth ? "max-w-full" : "max-w-7xl"
+                } mx-auto px-4 sm:px-6 lg:px-8 pt-8`}
+            >
+                {/* Account Summary */}
+                <section className="mb-2">
+                    {/* <div className="flex justify-between items-end mb-4">
+                        <h1 className="text-2xl font-bold text-white">
+                            Overview
+                        </h1>
+                        <span className="text-xs text-slate-500 bg-slate-800 px-2 py-1 rounded border border-slate-700">
+                            Currency: {account.currency}
+                        </span>
+                    </div> */}
+                    <SummaryCard account={account} />
+                </section>
+
+                {/* Charts Section */}
+                <section className="mb-8">
+                    <PortfolioChart positions={positions} />
+                </section>
+
+                {/* Positions Table */}
+                <section>
+                    <PositionsTable positions={positions} />
+                </section>
+            </main>
+        </div>
+    );
+};
+
+export default App;

README.md

@@ -1 +1,76 @@
-# Alloc
+# Alloc
+
+Stock Portfolio Visualization made for [FUTU/Moomoo](https://www.moomoo.com/) users.
+
+## Read Me First
+
+This is a web app that visualizes your stock portfolio data purely from the browser-side (client-side, locally). It does not require any server-side processing or database.
+
+[FUTU/Moomoo](https://www.moomoo.com/) does not provide proper scope-managed API for third-party apps. Thus, for 100% security and privacy, this app does not ask for any account credentials or tokens. Instead, it relies on you to export your portfolio data via moomoo's official API yourself. We provide a simple script to do that and the script doesn't handle any part of the authentication.
+
+Read the following section for step-by-step instructions.
+
+## Exporting Portfolio Data
+
+### Prerequisites
+
+-   You need to be a [FUTU/Moomoo](https://www.moomoo.com/) user with an active account, anywhere in the world (incl. US, HK, SG, etc.).
+
+### Step 1: Setup Moomoo API Client Locally
+
+1. Download the latest [moomoo OpenD GUI Client](https://www.moomoo.com/download/OpenAPI?_ga=2.228072795.755266222.1765942756-812069572.1761661575&_gac=1.190289369.1765944929.Cj0KCQiAo4TKBhDRARIsAGW29bdGCT3yyW5G99CEqHuhi0rb6N6xPiw4oVzmKEURl0xcbzfzn8wOFo8aAmzkEALw_wcB&chain_id=KXCd6VRrpQ6J-S.1kk4cl5&global_content=%7B%22promote_id%22%3A1010,%22sub_promote_id%22%3A344,%22f%22%3A%22mm%2Fsg%2Fsupport%2Ftopic3_441%22%7D) to your local machine.
+    - Choose `moomoo OpenAPI` > `moomoo OpenD` > Latest Version.
+    - Note that you are downloading `moomoo OpenD` instead of `moomoo API`.
+    - After downloading, run the installer and follow the instructions to install it.
+2. Run the `moomoo OpenD` client and login to your [FUTU/Moomoo](https://www.moomoo.com/) account.
+    - Use all default settings and login with your account credentials. By default, it should have parameters like:
+        - `IP`: `127.0.0.1`
+        - `Port`: `11111`
+    - When you login for the first time on a new device, it will ask you to authenticate via 2FA. Save your login details and check the automatic login checkbox will allow you to login smoothly next time.
+    - Once you are logged in, leave it running in the background.
+
+### Step 2: Run the Export Script
+
+1. Clone this repository:
+
+    ```bash
+    git clone https://github.com/mxshell/Alloc.git
+    cd Alloc
+    ```
+
+2. Set up the Python environment:
+
+    ```bash
+    cd python
+    uv sync
+    ```
+
+3. Run the export script:
+
+    ```bash
+    uv run moomoo_export.py
+    ```
+
+    - After the script is done, you will find the exported data (a single JSON file) in the `python` directory.
+    - Once you have the exported data, you can close/terminate the `moomoo OpenD` client.
+
+## Run `Alloc` Web App Locally
+
+**Environment:**
+
+-   `Node.js`
+-   `pnpm` (optional, but recommended)
+
+**Commands:**
+
+1. Install app dependencies:
+   `pnpm install` or `npm install`
+2. Run the app:
+   `pnpm run dev` or `npm run dev`
+
+## Using `Alloc` Web App
+
+1. Open the `Alloc` web app in your browser.
+    - Publicly hosted at [https://mxshell.dev/Alloc](https://mxshell.dev/Alloc/)
+    - or use your locally hosted app by opening [http://localhost:3000](http://localhost:3000) in your browser.
+2. Simply drag and drop the exported JSON file into the app.