# epeltz33/stockwatch architecture

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

- Interactive diagram: https://gitdiagram.com/epeltz33/stockwatch
- Repository: https://github.com/epeltz33/stockwatch

## Overview

##### Main Components

A. Frontend Layer:
- Dual-frontend architecture:
- Traditional Flask templates (in app/templates/)
- Plotly Dash components (in frontend/)
- How these interact with the backend

B. Backend Layer:
- Flask Application Core
- Blueprint Modules:
- Auth Blueprint (authentication)
- Main Blueprint (core pages)
- Stock Blueprint (stock-related operations)
- User Blueprint (user management)
- Services Layer:
- Stock Services
- User Services

C. External Services:
- Polygon.io API Integration
- Cache System (indicated by cache_monitor.py)

D. Data Layer:
- SQLite Database
- SQLAlchemy ORM
- Migration System (Alembic)

##### Component Relationships

**[Client Browser] ←→ [Frontend Layer (Flask Templates + Plotly Dash)]**
- ↓↑
**[Authentication Layer (auth.py)] → [User Services]**
- ↓↑
**[Application Core (Flask)] → [Blueprints]**
- ↓↑
**[Services Layer] → [Stock Services, User Services]**
- ↓↑
**[External API Layer] → [Polygon.io API]**
- ↓↑
**[Data Layer] → [SQLite + SQLAlchemy]**

##### Important Elements to Emphasize

A. Security Flow:
- Authentication flow through auth blueprint
- Secure routes and middleware

B. Data Flow:
- Stock data retrieval path from Polygon.io
- Caching mechanism for optimization
- Database interactions

C. User Interface Components:
- Separate flows for template-based pages vs. Dash components
- How they integrate in the frontend

##### Specific Implementation Details

- app.py (Main application entry)
- config.py (Configuration management)
- extensions.py (Flask extensions)
- models.py (Database models)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Browser["Web Browser"]
    end

    subgraph "Frontend Layer"
        Templates["Flask Templates"]:::frontend
        DashComponents["Plotly Dash Components"]:::frontend
        StaticAssets["Static Assets"]:::frontend
        FrontendAssets["Frontend Assets"]:::frontend
    end

    subgraph "Authentication Layer"
        AuthBP["Auth Blueprint"]:::auth
        AuthMiddleware["Auth Middleware"]:::auth
    end

    subgraph "Application Core"
        FlaskApp["Flask Application"]:::core
        Config["Configuration"]:::core
        Extensions["Flask Extensions"]:::core
    end

    subgraph "Blueprint Layer"
        MainBP["Main Blueprint"]:::blueprint
        StockBP["Stock Blueprint"]:::blueprint
        UserBP["User Blueprint"]:::blueprint
    end

    subgraph "Services Layer"
        StockServices["Stock Services"]:::service
        UserServices["User Services"]:::service
    end

    subgraph "External Services"
        PolygonAPI["Polygon.io API"]:::external
        CacheSystem["Cache System"]:::external
    end

    subgraph "Data Layer"
        Database["SQLite Database"]:::database
        ORM["SQLAlchemy ORM"]:::database
        Migrations["Database Migrations"]:::database
        Models["Database Models"]:::database
    end

    %% Relationships
    Browser --> Templates
    Browser --> DashComponents
    Templates --> AuthBP
    DashComponents --> AuthBP
    AuthBP --> FlaskApp
    FlaskApp --> MainBP
    FlaskApp --> StockBP
    FlaskApp --> UserBP
    MainBP --> StockServices
    StockBP --> StockServices
    UserBP --> UserServices
    StockServices --> PolygonAPI
    StockServices --> CacheSystem
    UserServices --> Models
    StockServices --> Models
    Models --> ORM
    ORM --> Database
    Migrations --> Database

    %% Click Events
    click Templates "https://github.com/epeltz33/StockWatch/tree/main/app/templates/"
    click DashComponents "https://github.com/epeltz33/StockWatch/blob/main/frontend/dashboard.py"
    click AuthBP "https://github.com/epeltz33/StockWatch/blob/main/app/blueprints/auth.py"
    click MainBP "https://github.com/epeltz33/StockWatch/blob/main/app/blueprints/main.py"
    click StockBP "https://github.com/epeltz33/StockWatch/blob/main/app/blueprints/stock.py"
    click UserBP "https://github.com/epeltz33/StockWatch/blob/main/app/blueprints/user.py"
    click StockServices "https://github.com/epeltz33/StockWatch/blob/main/app/services/stock_services.py"
    click UserServices "https://github.com/epeltz33/StockWatch/blob/main/app/services/user_services.py"
    click CacheSystem "https://github.com/epeltz33/StockWatch/blob/main/app/utils/cache_monitor.py"
    click Models "https://github.com/epeltz33/StockWatch/blob/main/app/models.py"
    click Migrations "https://github.com/epeltz33/StockWatch/tree/main/migrations/"
    click FlaskApp "https://github.com/epeltz33/StockWatch/blob/main/app/__init__.py"
    click Config "https://github.com/epeltz33/StockWatch/blob/main/config.py"
    click Extensions "https://github.com/epeltz33/StockWatch/blob/main/app/extensions.py"
    click StaticAssets "https://github.com/epeltz33/StockWatch/tree/main/app/static/"
    click FrontendAssets "https://github.com/epeltz33/StockWatch/tree/main/frontend/assets/"

    %% Styling
    classDef frontend fill:#3498db
    classDef auth fill:#e74c3c
    classDef core fill:#2ecc71
    classDef blueprint fill:#95a5a6
    classDef service fill:#f1c40f
    classDef external fill:#e67e22
    classDef database fill:#9b59b6

    %% Legend
    subgraph Legend
        Frontend["Frontend Component"]:::frontend
        Auth["Auth Component"]:::auth
        Core["Core Component"]:::core
        Blueprint["Blueprint Component"]:::blueprint
        Service["Service Component"]:::service
        External["External Component"]:::external
        Database["Database Component"]:::database
    end
```
