# aymmaann/lunex architecture

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

- Interactive diagram: https://gitdiagram.com/aymmaann/lunex
- Repository: https://github.com/aymmaann/lunex

## Overview

##### Project type and purpose
- The **client** folder contains a React (Vite) single‑page application for browsing coins, viewing history, managing a wallet, and chatting with an AI assistant (FinBot).
- The **server** folder contains a Node.js/Express REST API that handles authentication, coin data persistence, analysis, and integration with Google Cloud services.

##### File structure
- Top‑level:
- client/ – React SPA (Vite)
- server/ – Express API
- client/src: organized by components, pages, services (api calls, auth, crypto analysis), context, assets.
- server: follows MVC-like separation:
- controllers/ – map HTTP routes to business logic
- services/ – core crypto data fetching/analysis logic
- handlers/ – specialized functions (e.g., cryptoAnalysisHandler)
- models/ – data schemas for Datastore (userModel, coinModel)
- middleware/ – auth checks (JWT/OAuth)
- routes/router.js – express routing
- utils/ – cloud config, export functions

##### README for additional insights
- Uses Google Cloud (Datastore, BigQuery, Storage, Run, Scheduler, Secret Manager)
- External APIs: CoinGecko, Google Gemini
- OAuth for user authentication
- Scheduled jobs to refresh crypto values every 5 minutes

a. Main components:
- Frontend: React SPA (Vite)
- Backend API: Node.js/Express (hosted in Cloud Run)
- Datastore: Google Cloud Datastore for users & saved/invested cryptos
- BigQuery: analytics on exported data
- Cloud Storage: intermediate storage of exported JSON/CSV
- Cloud Scheduler: triggers export/refresh jobs
- External Services: CoinGecko API, Google Gemini API, OAuth (Google)
b. Relationships & interactions:
1. User → React SPA → calls Express endpoints (via VITE_API_URL)
2. Express → authenticates user via OAuth → stores user in Datastore
3. React SPA → fetches market data from Express → Express → CoinGecko
4. React SPA → triggers FinBot chat → Express → Gemini API → returns response
5. Cloud Scheduler → invokes Express endpoint → refreshes prices in Datastore
6. Export service in Express → dumps Datastore → Cloud Storage → BigQuery load
7. React SPA → fetches analytics queries (optionally via Express or directly BigQuery)
c. Architectural patterns & principles:
- Frontend: single‑page application, component‑based design, context for global state, separation of concerns (services for API calls)
- Backend: layered architecture (router → controller → service → model), stateless services in Cloud Run, JWT/OAuth middleware
- Cloud Integration: serverless services for scalability, event‑driven pipeline (Scheduler → Cloud Run → Storage → BigQuery)
d. Key technologies & libraries:
- Frontend: React, Vite, Tailwind, Context API, Axios/fetch for REST, Google OAuth JS SDK, Gemini client
- Backend: Node.js, Express, @google-cloud/datastore, dotenv, jsonwebtoken, cross‑service utilities
- Cloud: Cloud Run, Datastore, BigQuery, Cloud Storage, Secret Manager, Scheduler

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% FRONTEND
    subgraph "Frontend (Browser)" 
        direction TB
        ReactSPA["React SPA"]:::frontend
        click ReactSPA "https://github.com/aymmaann/lunex/tree/master/client/"

        subgraph "Configuration" 
            direction TB
            Vite["vite.config.js"]:::frontend
            click Vite "https://github.com/aymmaann/lunex/blob/master/client/vite.config.js"
            Tailwind["tailwind.config.js"]:::frontend
            click Tailwind "https://github.com/aymmaann/lunex/blob/master/client/tailwind.config.js"
            HTML["index.html"]:::frontend
            click HTML "https://github.com/aymmaann/lunex/blob/master/client/index.html"
        end

        subgraph "Entry & Styles" 
            direction TB
            Main["main.jsx"]:::frontend
            click Main "https://github.com/aymmaann/lunex/blob/master/client/src/main.jsx"
            Styles["index.css"]:::frontend
            click Styles "https://github.com/aymmaann/lunex/blob/master/client/src/index.css"
            AppRoot["App.jsx"]:::frontend
            click AppRoot "https://github.com/aymmaann/lunex/blob/master/client/src/App.jsx"
        end

        subgraph "Services & Context" 
            direction TB
            APIsvc["api.js"]:::frontend
            click APIsvc "https://github.com/aymmaann/lunex/blob/master/client/src/services/api.js"
            Authsvc["auth.js"]:::frontend
            click Authsvc "https://github.com/aymmaann/lunex/blob/master/client/src/services/auth.js"
            CryptoAnalyser["cryptoAnalysisService.js"]:::frontend
            click CryptoAnalyser "https://github.com/aymmaann/lunex/blob/master/client/src/services/cryptoAnalysisService.js"
            GeminiContext["GeminiContext.jsx"]:::frontend
            click GeminiContext "https://github.com/aymmaann/lunex/blob/master/client/src/context/GeminiContext.jsx"
            GeminiConfig["gemini.js"]:::frontend
            click GeminiConfig "https://github.com/aymmaann/lunex/blob/master/client/src/config/gemini.js"
        end

        subgraph "UI Components" 
            direction TB
            Navbar["Navbar.jsx"]:::frontend
            click Navbar "https://github.com/aymmaann/lunex/blob/master/client/src/components/Navbar.jsx"
            CryptoCard["CryptoCard.jsx"]:::frontend
            click CryptoCard "https://github.com/aymmaann/lunex/blob/master/client/src/components/CryptoCard.jsx"
            Trending["TrendingCrypto.jsx"]:::frontend
            click Trending "https://github.com/aymmaann/lunex/blob/master/client/src/components/TrendingCrypto.jsx"
            Portfolio["PortfolioSummary.jsx"]:::frontend
            click Portfolio "https://github.com/aymmaann/lunex/blob/master/client/src/components/PortfolioSummary.jsx"
            WalletCard["WalletCard.jsx"]:::frontend
            click WalletCard "https://github.com/aymmaann/lunex/blob/master/client/src/components/WalletCard.jsx"
            Modals["Modal.jsx"]:::frontend
            click Modals "https://github.com/aymmaann/lunex/blob/master/client/src/components/Modal.jsx"
        end

        subgraph "Pages (Routes)" 
            direction TB
            Home["Home.jsx"]:::frontend
            click Home "https://github.com/aymmaann/lunex/blob/master/client/src/pages/Home.jsx"
            Market["Market.jsx"]:::frontend
            click Market "https://github.com/aymmaann/lunex/blob/master/client/src/pages/Market.jsx"
            WalletPage["Wallet.jsx"]:::frontend
            click WalletPage "https://github.com/aymmaann/lunex/blob/master/client/src/pages/Wallet.jsx"
            FinBot["FinBot.jsx"]:::frontend
            click FinBot "https://github.com/aymmaann/lunex/blob/master/client/src/pages/FinBot.jsx"
            Login["Login.jsx"]:::frontend
            click Login "https://github.com/aymmaann/lunex/blob/master/client/src/pages/Login.jsx"
        end
    end

    %% BACKEND
    subgraph "Backend/Cloud" 
        direction TB
        subgraph "Express API (Cloud Run)" 
            direction TB
            APIEntry["index.js"]:::backend
            click APIEntry "https://github.com/aymmaann/lunex/blob/master/server/index.js"
            Router["router.js"]:::backend
            click Router "https://github.com/aymmaann/lunex/blob/master/server/routes/router.js"
            subgraph "Controllers" 
                direction TB
                AuthCtrl["authController.js"]:::backend
                click AuthCtrl "https://github.com/aymmaann/lunex/blob/master/server/controllers/authController.js"
                CoinCtrl["coinController.js"]:::backend
                click CoinCtrl "https://github.com/aymmaann/lunex/blob/master/server/controllers/coinController.js"
            end
            subgraph "Middleware" 
                direction TB
                AuthMW["authMiddleware.js"]:::backend
                click AuthMW "https://github.com/aymmaann/lunex/blob/master/server/middleware/authMiddleware.js"
            end
            subgraph "Services" 
                direction TB
                CryptoSvc["cryptoServices.js"]:::backend
                click CryptoSvc "https://github.com/aymmaann/lunex/blob/master/server/services/cryptoServices.js"
            end
            subgraph "Handlers" 
                direction TB
                AnalysisH["cryptoAnalysisHandler.js"]:::backend
                click AnalysisH "https://github.com/aymmaann/lunex/blob/master/server/handlers/cryptoAnalysisHandler.js"
            end
            subgraph "Models" 
                direction TB
                UserModel["userModel.js"]:::backend
                click UserModel "https://github.com/aymmaann/lunex/blob/master/server/models/userModel.js"
                CoinModel["coinModel.js"]:::backend
                click CoinModel "https://github.com/aymmaann/lunex/blob/master/server/models/coinModel.js"
            end
            subgraph "Utils" 
                direction TB
                GoogleCfg["googleConfig.js"]:::backend
                click GoogleCfg "https://github.com/aymmaann/lunex/blob/master/server/utils/googleConfig.js"
                ExportUtil["exportAnalysis.js"]:::backend
                click ExportUtil "https://github.com/aymmaann/lunex/blob/master/server/utils/exportAnalysis.js"
            end
        end

        subgraph "Data Stores" 
            direction TB
            Datastore["Cloud Datastore"]:::datastore
            BigQuery["BigQuery"]:::datastore
            Storage["Cloud Storage"]:::datastore
            SecretMgr["Secret Manager"]:::datastore
            Scheduler["Cloud Scheduler"]:::datastore
        end
    end

    %% EXTERNAL SERVICES
    CoinGecko["CoinGecko API"]:::external
    Gemini["Google Gemini"]:::external
    OAuth["Google OAuth"]:::external

    %% FLOWS
    ReactSPA -->|HTTP/REST| Router
    Router -->|calls| AuthCtrl
    Router -->|calls| CoinCtrl
    AuthCtrl -->|uses| UserModel
    CoinCtrl -->|uses| CoinModel
    CoinCtrl -->|calls| CryptoSvc
    CryptoSvc -->|fetches| CoinGecko
    CryptoSvc -->|persists| Datastore
    AnalysisH -->|calls| Gemini
    CryptoSvc -->|reads secrets| SecretMgr
    Scheduler -->|invokes refresh| Router
    ExportUtil -->|exports| Datastore
    ExportUtil -->|writes| Storage
    Storage -->|loads| BigQuery
    ReactSPA -->|OAuth flow| OAuth
    ReactSPA -->|chat| AnalysisH
    ReactSPA -->|analytics| BigQuery

    %% STYLES
    classDef frontend fill:#cce5ff,stroke:#2a7cff,color:#000
    classDef backend fill:#d4edda,stroke:#28a745,color:#000
    classDef datastore fill:#ffe5b4,stroke:#ff8c00,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
```
