# wyattlin001/invest_v3 architecture

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

- Interactive diagram: https://gitdiagram.com/wyattlin001/invest_v3
- Repository: https://github.com/wyattlin001/invest_v3

## Overview

##### Project type and purpose
- This is a full-stack “Invest Simulator” platform consisting of an iOS SwiftUI front-end, a Flask-based REST API back-end, and a PostgreSQL database (self-hosted or via Supabase). It also integrates external services (yfinance for market data, Twilio for OTP SMS) and runs scheduled jobs (price updates, ranking calculations).

##### File structure
- Top-level directories:
- Invest_V3/ – iOS SwiftUI app (Views, ViewModels, Models, Services)
- invest_simulator_backend/ – Flask back-end (app.py, services/, SQL scripts, tests)
- dependency_analysis/ & dependency_reports/ – code analysis tooling
- Tests and docs at root
- Patterns:
- iOS uses MVVM (View + ViewModel + Service)
- Back-end uses a service-layer pattern (auth_service, db_service, trading_service, market_data_service, scheduler_service)
- Build/deploy scripts, Dockerfile, SQL schema scripts

##### README for technical stack
- Front-end: SwiftUI (iOS 15+, Xcode 14+), MVVM, Combine
- Back-end: Flask (Python 3.8+), RESTful endpoints, scheduler tasks
- Database: PostgreSQL via Supabase (Auth, Real-time, Storage)
- External services: yfinance, Twilio SMS
- Scheduler: periodic jobs (every 30s, 1m, 5m)

##### Key components
a. Front-end (iOS SwiftUI)
- Views (AuthenticationView, TradingMainView, etc.)
- ViewModels (TradingViewModel, ChatViewModel, etc.)
- Network/Service layer (TradingService.swift, SupabaseService.swift)
b. Back-end (Flask API)
- app.py (routing)
- Service modules:
- auth_service.py (OTP, JWT)
- db_service.py (CRUD)
- trading_service.py (buy/sell logic)
- market_data_service.py (yfinance integration)
- scheduler_service.py (job scheduling)
c. Persistence and real-time
- PostgreSQL (tables: users, portfolios, transactions, rankings)
- Supabase (authentication, real-time updates, optional as a BaaS)
d. External integrations
- yfinance API (stock price data)
- Twilio SMS (OTP delivery)
e. Scheduler subsystem
- Cron-style tasks invoking market_data_service and ranking updates

##### Relationships and interactions
- iOS App ↔ (REST calls) ↔ Flask API
- iOS App ↔ (SDK/API calls) ↔ Supabase Auth & Real-time
- Flask API → PostgreSQL (via db_service)
- Flask scheduler → market_data_service → yfinance
- Flask auth_service → Twilio SMS
- Scheduler triggers ranking and portfolio recalculations

##### Architectural patterns and design principles
- MVVM in the iOS client for separation of UI and business logic
- Layered service architecture in the Flask back-end
- Clear separation of concerns: Authentication, Trading, Market Data, Scheduling
- Use of BaaS (Supabase) for auth and real-time capabilities
- Stateless REST API with JWT tokens for security

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% iOS Front-end
    subgraph "iOS SwiftUI (MVVM)"
        direction TB
        subgraph Views
            direction TB
            AuthView["AuthenticationView"]:::frontend
            TradingMainView["TradingMainView"]:::frontend
            ChatView["ChatView"]:::frontend
            PortfolioView["PortfolioView"]:::frontend
            RankingsView["RankingsView"]:::frontend
        end
        subgraph "ViewModels"
            direction TB
            TradingVM["TradingViewModel"]:::frontend
            ChatVM["ChatViewModel"]:::frontend
            HomeVM["HomeViewModel"]:::frontend
            SettingsVM["SettingsViewModel"]:::frontend
            WalletVM["WalletViewModel"]:::frontend
        end
        subgraph "Service Layer"
            direction TB
            TradingSvc["TradingService"]:::frontend
            SupabaseSvc["SupabaseService"]:::frontend
            PortfolioSvc["PortfolioService"]:::frontend
            StockSvc["StockService"]:::frontend
            UserProfileSvc["UserProfileService"]:::frontend
        end
    end

    %% Flask Back-end
    subgraph "Flask API" 
        direction TB
        App["app.py"]:::backend
        Run["run.py"]:::backend
        subgraph "Services"
            direction TB
            AuthSvcBE["auth_service.py"]:::backend
            DBSvc["db_service.py"]:::backend
            TradingSvcBE["trading_service.py"]:::backend
            MarketDataSvc["market_data_service.py"]:::backend
            SchedulerSvc["scheduler_service.py"]:::scheduler
        end
    end

    %% Database and BaaS
    PostgreSQL["PostgreSQL"]:::db
    Supabase["Supabase Auth & Real-time"]:::db

    %% External Services
    YFinance["yfinance API"]:::external
    Twilio["Twilio SMS"]:::external

    %% Connections
    AuthView -->|"binds to"| TradingVM
    TradingMainView -->|"binds to"| TradingVM
    ChatView -->|"binds to"| ChatVM
    PortfolioView -->|"binds to"| HomeVM
    RankingsView -->|"binds to"| HomeVM

    TradingVM -->|"calls"| TradingSvc
    ChatVM -->|"calls"| TradingSvc
    HomeVM -->|"calls"| PortfolioSvc
    SettingsVM -->|"calls"| UserProfileSvc
    WalletVM -->|"calls"| PortfolioSvc

    TradingSvc -->|"HTTPS/REST"| App
    SupabaseSvc -->|"SDK/WebSocket"| Supabase
    PortfolioSvc -->|"HTTPS/REST"| App
    StockSvc -->|"HTTPS/REST"| App
    UserProfileSvc -->|"HTTPS/REST"| App

    App -->|"routes to"| AuthSvcBE
    App -->|"routes to"| TradingSvcBE
    App -->|"routes to"| MarketDataSvc
    App -->|"routes to"| SchedulerSvc
    App -->|"uses"| DBSvc

    AuthSvcBE -->|"sends OTP"| Twilio
    AuthSvcBE -->|"issues JWT"| TradingSvcBE

    TradingSvcBE -->|"CRUD"| DBSvc
    DBSvc -->|"connects to"| PostgreSQL

    SchedulerSvc -->|"triggers every 30s/1m/5m"| MarketDataSvc
    SchedulerSvc -->|"triggers ranking update"| TradingSvcBE

    MarketDataSvc -->|"fetches data"| YFinance
    MarketDataSvc -->|"stores prices"| DBSvc

    PostgreSQL -->|"data| to queries"| TradingSvcBE
    Supabase -->|"real-time updates"| AuthView

    %% Click events for iOS Front-end Views
    click AuthView "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/AuthenticationView.swift"
    click TradingMainView "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/TradingMainView.swift"
    click ChatView "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/ChatView.swift"
    click PortfolioView "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/PortfolioView.swift"
    click RankingsView "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/RankingsView.swift"

    %% Click events for iOS ViewModels
    click TradingVM "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/TradingViewModel.swift"
    click ChatVM "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/ChatViewModel.swift"
    click HomeVM "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/HomeViewModel.swift"
    click SettingsVM "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/SettingsViewModel.swift"
    click WalletVM "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/WalletViewModel.swift"

    %% Click events for iOS Services
    click TradingSvc "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/TradingService.swift"
    click SupabaseSvc "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/SupabaseService.swift"
    click PortfolioSvc "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/PortfolioService.swift"
    click StockSvc "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/StockService.swift"
    click UserProfileSvc "https://github.com/wyattlin001/invest_v3/blob/main/Invest_V3/UserProfileService.swift"

    %% Click events for Back-end
    click App "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/app.py"
    click Run "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/run.py"
    click AuthSvcBE "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/services/auth_service.py"
    click DBSvc "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/services/db_service.py"
    click TradingSvcBE "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/services/trading_service.py"
    click MarketDataSvc "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/services/market_data_service.py"
    click SchedulerSvc "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/services/scheduler_service.py"

    %% Click events for Database scripts
    click PostgreSQL "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/init_database.sql"
    click PostgreSQL "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/setup_trading_tables.sql"
    click PostgreSQL "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/setup_rankings_table.sql"
    click Supabase "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/.env.example"

    %% Click events for External Integrations
    click YFinance "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/services/market_data_service.py"
    click Twilio "https://github.com/wyattlin001/invest_v3/blob/main/invest_simulator_backend/services/auth_service.py"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef db fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef scheduler fill:#fff3cd,stroke:#856404,color:#856404;
```
