# quangngonz/isph-se-pubsub-services architecture

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

- Interactive diagram: https://gitdiagram.com/quangngonz/isph-se-pubsub-services
- Repository: https://github.com/quangngonz/isph-se-pubsub-services

## Overview

##### Main Components
- Engine & Event Processing:
- engine.js is the “heartbeat” of the system, simulating and triggering stock market events at random intervals.
- Under the functions directory, several modules (e.g., manipulateStockPrices.js, proccessEvent.js, saveCurrentPortfolioValue.js) handle evaluation and data processing.
- API and Server:
- server.js serves as the entry point, handling HTTP requests (such as the /trigger-task endpoint) and interfacing with other components.
- Services Layer:
- The services directory contains specific business logic. For example, services/evaluation (eventEvaluation.js, priceProjectionTransactions.js) implements AI-driven evaluation and projection.
- services/firebaseService.js represents integration with Firebase for real-time data management.
- External Integrations:
- The system integrates with third-party APIs (OpenAI and Google Gemini) for analytical tasks, as indicated in the README.
- There’s also a Redis integration (configured via the environment variable REDIS_URL) likely for caching or message brokering.
- Deployment and CI/CD:
- The presence of Heroku-related configuration (heroku_config.py, Procfile) indicates deployment automation.
- GitHub workflows (in .github/workflows) show automated quality checks.
- Test Suite:
- The test directory includes Python scripts for firing events, generating test data (both CSV and JSON formats), and pushing data to Firebase. This indicates a robust testing framework for simulation and validation.

##### Out Relationships and Interactions
- The engine (engine.js) continuously triggers event processing functions in the functions directory.
- API endpoints (defined in server.js) allow external triggering of tasks (e.g., via POST /trigger-task).
- These tasks interact with the services layer:
- The evaluation services process and project stock prices.
- The Firebase service updates the real-time database.
- Scheduled and background tasks (like saving portfolio values via saveCurrentPortfolioValue.js) run at fixed intervals.
- Data flows from historical and current event data into the evaluation modules and then outputs back to both Firebase (for real-time data) and potential external consumers (through API responses).

##### Architectural Patterns and Design Principles
- Modularization: The design clearly separates various concerns into discrete modules (functions, services, tests).
- Pub/Sub and Event-Driven Design: The system uses an event-based approach to trigger stock evaluations and projections.
- External API Integration: The usage of AI-based evaluations highlights integration patterns with external services (OpenAI, Gemini).
- Deployment and Automation: CI/CD practices via GitHub workflows and Heroku configuration illustrate adherence to modern DevOps practices.

##### Relevant Technologies, Frameworks, and Libraries
- Node.js for the runtime environment.
- Firebase for real-time data handling.
- Heroku for deployment.
- CI tools as seen in the Qodana and GitHub Actions workflow.
- Python scripts for auxiliary testing and data generation.
- External APIs (OpenAI and Google Gemini) to drive the AI logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "ISPH Stock Exchange Pub/Sub Services"
        E["Engine (engine.js)"]:::engine
        subgraph "Event Functions"
            FP1["manipulateStockPrices (functions/manipulateStockPrices.js)"]:::functions
            FP2["proccessEvent (functions/proccessEvent.js)"]:::functions
            FP3["saveCurrentPortfolioValue (functions/saveCurrentPortfolioValue.js)"]:::functions
        end
        AP["API Server (server.js)"]:::server
        subgraph "Services"
            subgraph "Evaluation Services"
                EV1["eventEvaluation (services/evaluation/eventEvaluation.js)"]:::evaluation
                EV2["priceProjectionTransactions (services/evaluation/priceProjectionTransactions.js)"]:::evaluation
            end
            FS["Firebase Service (services/firebaseService.js)"]:::firebase
        end
    end

    subgraph "External Integrations"
        AI1["OpenAI&GoogleGemini"]:::external
        RE["Redis"]:::external
        LLM["LLMServices (functions/utils/LLMServices.js)"]:::functions
    end

    subgraph "CI/CD & Deployment"
        HD["Heroku Deployment"]:::deployment
        GH["GitHubActions&CI"]:::deployment
    end

    subgraph "Test Suite"
        TS["Test Directory"]:::test
    end

    E -->|"EventTrigger"| FP1
    E -->|"EventTrigger"| FP2
    E -->|"ScheduledTrigger"| FP3
    FP1 -->|"ProcessesData"| EV1
    FP2 -->|"ProcessesEvent"| EV1
    FP1 -->|"PriceUpdate"| EV2
    FP2 -->|"EventProcessing"| EV2
    EV1 -->|"EvaluationResult"| FS
    EV2 -->|"ProjectionResult"| FS
    AP -->|"APICall_trigger-task"| E
    E -->|"Uses"| LLM
    EV1 -->|"IntegratesWith"| AI1
    EV2 -->|"IntegratesWith"| AI1
    FP2 -->|"UsesCaching"| RE
    FS -->|"RealtimeUpdate"| AP
    AP -->|"DeployedOn"| HD
    E -->|"DeployedOn"| HD
    FS -->|"DeployedOn"| HD
    EV1 -->|"CI/CD"| GH
    EV2 -->|"CI/CD"| GH
    AP -->|"CI/CD"| GH
    TS -->|"SimulatesEvents"| E

    click E "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/engine.js"
    click FP1 "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/functions/manipulateStockPrices.js"
    click FP2 "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/functions/proccessEvent.js"
    click FP3 "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/functions/saveCurrentPortfolioValue.js"
    click AP "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/server.js"
    click EV1 "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/services/evaluation/eventEvaluation.js"
    click EV2 "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/services/evaluation/priceProjectionTransactions.js"
    click FS "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/services/firebaseService.js"
    click LLM "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/functions/utils/LLMServices.js"
    click HD "https://github.com/quangngonz/isph-se-pubsub-services/tree/main/Procfile"
    click HD "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/heroku_config.py"
    click GH "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/.github/workflows/qodana_code_quality.yml"
    click GH "https://github.com/quangngonz/isph-se-pubsub-services/blob/main/qodana.yaml"
    click TS "https://github.com/quangngonz/isph-se-pubsub-services/tree/main/test"

    classDef engine fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef functions fill:#ffeecc,stroke:#333,stroke-width:2px;
    classDef server fill:#aqua,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef firebase fill:#ccffff,stroke:#333,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-dasharray:5 5,stroke-width:2px;
    classDef deployment fill:#e6ccff,stroke:#333,stroke-width:2px;
    classDef test fill:#ccccff,stroke:#333,stroke-width:2px;
```
