# normancao2702/cmpt362-stocksim architecture

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

- Interactive diagram: https://gitdiagram.com/normancao2702/cmpt362-stocksim
- Repository: https://github.com/normancao2702/cmpt362-stocksim

## Overview

##### Project Type and Purpose
- This is a full-stack Android mobile application (Kotlin) built under the MVVM pattern.
- Purpose: A stock-trading simulator where users start with 10,000 USD, fetch live stock prices via the Polygon API, track profits and portfolio value, and unlock achievements. It also includes social features (posts, friends, chat).
- The app communicates with:
– Polygon external API for live stock data
– A backend service (not in this repo) managing user accounts, achievements, portfolios, social posts, chat, all persisted in a MariaDB database

##### File Structure Analysis
- Top-level module “app” (Gradle/Kotlin DSL) contains:
– src/main/java/com/example/cmpt362_stocksim/…
- api: BackendRepository, ViewModel, ViewModelFactory
- ui: multiple features (auth, dashboard, home, inventory, notifications, portfolio, search, social) each with Activities/Fragments and ViewModels/Adapters
- userDataManager: business-logic managers (UserDataManager, NetWorthHistoryManager)
- utils: JWT helpers
– src/main/res: all Android UI resources (layouts, drawables, navigation, themes)
– src/androidTest and src/test for instrumentation and unit tests
- Build artifacts and configuration: build.gradle.kts, proguard, gradle wrapper

##### README Insights
- Highlights three core layers: View (Activities/Fragments), ViewModel, Repository (data sources).
- Mentions two external data endpoints:
– Polygon API (stock quotes)
– Custom backend with MariaDB (user data, history, social)

a. Main Components
- Android Client
– UI Layer: Activities & Fragments (Login, Register, Dashboard, etc.)
– ViewModel Layer: one per feature, exposes LiveData/StateFlow
– Repository Layer: BackendRepository – single entry point for data operations
– Local Managers: UserDataManager, NetWorthHistoryManager (caching/histories)
– Utilities: JwtUtils, UserJwtData (for auth token handling)
- External Services
– Polygon API (HTTPS REST)
– Custom Backend Service (HTTPS REST)
- Auth endpoints, portfolio endpoints, achievements endpoints, social/chat endpoints
- Persistence in MariaDB
- Database
– MariaDB hosting user credentials (encrypted), transactions, achievements, posts, chat history, stock metadata

b. Relationships and Interactions
- UI → ViewModel: Two-way data binding or LiveData/observers.
- ViewModel → Repository: invokes suspend functions or Rx calls.
- Repository → External Services: Retrofit/okhttp calls to Polygon and backend.
- External Services → MariaDB: backend query/update user data.
- Repository returns domain models to ViewModel which updates UI.
- UserDataManager caches token and history locally (in memory or lightweight storage).

c. Architectural Patterns & Principles
- MVVM: clear separation of concerns (UI, state, data).
- Single Repository: encapsulates all remote data sources.
- Dependency Injection (ViewModelFactory).
- Layered architecture: UI → VM → Repo → Network/DB.
- Resource management: background threads (Coroutines) ensure non-blocking UI.

d. Technologies, Frameworks, Libraries
- Kotlin + AndroidX (Fragments, ViewModel, LiveData)
- Retrofit/OkHttp for network calls
- Coroutines for threading
- MariaDB (backend)
- Polygon REST API
- JWT for authentication
- RecyclerView Adapters for lists (search, social feed, chat)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        MainActivity["MainActivity"]:::ui
        LoginActivity["LoginActivity"]:::ui
        RegisterActivity["RegisterActivity"]:::ui
        DashboardFragment["DashboardFragment"]:::ui
        HomeFragment["HomeFragment"]:::ui
        StockInventory["StockInventory"]:::ui
        NotificationsFragment["NotificationsFragment"]:::ui
        PortfolioFragment["PortfolioFragment"]:::ui
        SearchFragment["SearchFragment"]:::ui
        SocialFragment["SocialFragment"]:::ui
        AchievementActivity["AchievementActivity"]:::ui
    end

    %% ViewModel Layer
    subgraph "ViewModel Layer"
        direction TB
        DashboardViewModel["DashboardViewModel"]:::vm
        NotificationsViewModel["NotificationsViewModel"]:::vm
        PortfolioViewModel["PortfolioViewModel"]:::vm
        BackendViewModel["BackendViewModel"]:::vm
    end

    %% Repository & Managers
    subgraph "Repository Layer"
        direction TB
        BackendRepository["BackendRepository"]:::repo
        UserDataManager["UserDataManager"]:::repo
        NetWorthHistoryManager["NetWorthHistoryManager"]:::repo
        JwtUtils["JwtUtils"]:::repo
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PolygonAPI["Polygon API"]:::external
        BackendService["Custom Backend Service"]:::external
    end

    %% Database
    MariaDB["MariaDB"]:::db

    %% Connections
    MainActivity -->|uses| DashboardViewModel
    MainActivity -->|uses| BackendViewModel
    LoginActivity -->|uses| BackendViewModel
    RegisterActivity -->|uses| BackendViewModel
    DashboardFragment -->|binds| DashboardViewModel
    HomeFragment -->|binds| BackendViewModel
    StockInventory -->|binds| BackendViewModel
    NotificationsFragment -->|binds| NotificationsViewModel
    PortfolioFragment -->|binds| PortfolioViewModel
    SearchFragment -->|binds| BackendViewModel
    SocialFragment -->|binds| BackendViewModel
    AchievementActivity -->|binds| BackendViewModel

    DashboardViewModel -->|calls| BackendRepository
    NotificationsViewModel -->|calls| BackendRepository
    PortfolioViewModel -->|calls| BackendRepository
    BackendViewModel -->|calls| BackendRepository

    BackendRepository -->|fetches| PolygonAPI
    BackendRepository -->|fetches| BackendService
    BackendService -->|reads/writes| MariaDB

    BackendRepository -->|caches| UserDataManager
    BackendRepository -->|records| NetWorthHistoryManager
    BackendRepository -->|uses| JwtUtils

    %% Click Events
    click MainActivity "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/MainActivity.kt"
    click LoginActivity "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/auth/LoginActivity.kt"
    click RegisterActivity "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/auth/RegisterActivity.kt"
    click DashboardFragment "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/dashboard/DashboardFragment.kt"
    click DashboardViewModel "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/dashboard/DashboardViewModel.kt"
    click HomeFragment "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/home/HomeFragment.kt"
    click StockInventory "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/inventory/StockInventory.kt"
    click NotificationsFragment "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/notifications/NotificationsFragment.kt"
    click NotificationsViewModel "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/notifications/NotificationsViewModel.kt"
    click PortfolioFragment "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/portfolio/PortfolioFragment.kt"
    click PortfolioViewModel "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/portfolio/PortfolioViewModel.kt"
    click SearchFragment "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/ui/search/SearchFragment.kt"
    click BackendViewModel "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/api/BackendViewModel.kt"
    click BackendRepository "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/api/BackendRepository.kt"
    click UserDataManager "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/userDataManager/UserDataManager.kt"
    click NetWorthHistoryManager "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/userDataManager/NetWorthHistoryManager.kt"
    click JwtUtils "https://github.com/normancao2702/cmpt362-stocksim/blob/main/app/src/main/java/com/example/cmpt362_stocksim/utils/JwtUtils.kt"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#0D47A1;
    classDef vm fill:#C8E6C9,stroke:#1B5E20;
    classDef repo fill:#FFE0B2,stroke:#E65100;
    classDef external fill:#E1BEE7,stroke:#6A1B9A;
    classDef db fill:#CFD8DC,stroke:#37474F;
```
