# winillnwang/us-stock-intelligence-platform architecture

> Architecture diagram of the GitHub repository winillnwang/us-stock-intelligence-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/winillnwang/us-stock-intelligence-platform
- Repository: https://github.com/winillnwang/us-stock-intelligence-platform

## Overview

This is a Django-based US stock information platform. Its principal workflow ingests daily prices from Alpha Vantage, validates and transforms records, stores stock and OHLCV data, then serves authenticated REST queries and server-rendered search/detail pages with price analytics. A management command and standalone script provide ingestion entry points. The README also documents JWT and OpenAPI/Swagger capabilities, but their implementation details were not sampled; those links are therefore documented rather than inferred from unseen code.

Main entry points: [`backend/stocks/models.py`](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/models.py) (Stock Models), [`backend/stocks/services/alpha_vantage.py`](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/services/alpha_vantage.py) (Price Service), [`backend/stocks/api/views.py`](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/api/views.py) (Stock API), [`backend/stocks/management/commands/update_stock_prices.py`](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/management/commands/update_stock_prices.py) (Update Command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data Ingestion"]
  node_update_command["Update Command"]
  node_fetch_script["Fetch Script"]
  node_stock_config["Stock Config<br/>[stock_config.py]"]
  node_price_service["Price Service<br/>[alpha_vantage.py]"]
end

subgraph group_data["Price Data"]
  node_clean_prices["Price Validation<br/>[alpha_vantage.py]"]
  node_price_persistence["Price Persistence<br/>[alpha_vantage.py]"]
  node_stock_models["Stock Models<br/>[models.py]"]
  node_mysql[("MySQL Data")]
  node_stock_admin["Stock Admin<br/>[admin.py]"]
end

subgraph group_web["Web Experience"]
  node_web_views["Search and Analytics<br/>[views.py]"]
  node_web_templates["Stock Pages"]
end

subgraph group_delivery["API Delivery"]
  node_api_views["Stock API<br/>[views.py]"]
  node_serializers["API Serializers<br/>[serializers.py]"]
  node_api_routes["API Routes<br/>[urls.py]"]
  node_jwt["JWT Authentication<br/>[settings.py]"]
  node_api_docs["OpenAPI Docs<br/>[urls.py]"]
end

node_client(("API Client"))
node_market(("Alpha Vantage"))

node_update_command -->|"looks up"| node_stock_models
node_update_command -->|"updates prices"| node_price_service
node_fetch_script -->|"loads settings"| node_stock_config
node_fetch_script -->|"fetches and cleans"| node_price_service
node_price_service -->|"requests prices"| node_market
node_price_service -->|"transforms data"| node_clean_prices
node_price_service -->|"saves prices"| node_price_persistence
node_price_persistence -->|"writes records"| node_stock_models
node_stock_models -->|"persists via ORM"| node_mysql
node_web_views -->|"queries stocks"| node_stock_models
node_web_views -->|"renders pages"| node_web_templates
node_api_routes -->|"routes requests"| node_api_views
node_api_views -->|"queries records"| node_stock_models
node_api_views -->|"serializes results"| node_serializers
node_api_views -->|"requires authentication"| node_jwt
node_client -->|"requests data"| node_api_views
node_client -->|"obtains tokens"| node_jwt
node_client -->|"views documentation"| node_api_docs
node_stock_admin -->|"manages records"| node_stock_models

click node_update_command "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/management/commands/update_stock_prices.py"
click node_fetch_script "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/scripts/fetch_stock_data.py"
click node_stock_config "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/scripts/stock_config.py"
click node_price_service "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/services/alpha_vantage.py"
click node_clean_prices "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/services/alpha_vantage.py"
click node_price_persistence "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/services/alpha_vantage.py"
click node_stock_models "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/models.py"
click node_web_views "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/views.py"
click node_web_templates "https://github.com/winillnwang/us-stock-intelligence-platform/tree/master/backend/stocks/templates/stocks"
click node_api_views "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/api/views.py"
click node_serializers "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/api/serializers.py"
click node_api_routes "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/api/urls.py"
click node_jwt "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/config/settings.py"
click node_api_docs "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/config/urls.py"
click node_stock_admin "https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/admin.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_update_command,node_fetch_script,node_stock_config,node_price_service,node_client toneBlue
class node_clean_prices,node_price_persistence,node_stock_models,node_mysql,node_stock_admin toneAmber
class node_web_views,node_web_templates toneMint
class node_api_views,node_serializers,node_api_routes,node_jwt,node_api_docs toneRose
class node_market toneIndigo
```

## Components

### Data Ingestion

- [Update Command](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/management/commands/update_stock_prices.py): `backend/stocks/management/commands/update_stock_prices.py`
- [Fetch Script](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/scripts/fetch_stock_data.py): `scripts/fetch_stock_data.py`
- [Stock Config](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/scripts/stock_config.py): `scripts/stock_config.py`
- [Price Service](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/services/alpha_vantage.py): `backend/stocks/services/alpha_vantage.py`

### Price Data

- [Price Validation](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/services/alpha_vantage.py): `backend/stocks/services/alpha_vantage.py`
- [Price Persistence](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/services/alpha_vantage.py): `backend/stocks/services/alpha_vantage.py`
- [Stock Models](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/models.py): `backend/stocks/models.py`
- **MySQL Data**
- [Stock Admin](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/admin.py): `backend/stocks/admin.py`

### Web Experience

- [Search and Analytics](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/views.py): `backend/stocks/views.py`
- [Stock Pages](https://github.com/winillnwang/us-stock-intelligence-platform/tree/master/backend/stocks/templates/stocks): `backend/stocks/templates/stocks`

### API Delivery

- [Stock API](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/api/views.py): `backend/stocks/api/views.py`
- [API Serializers](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/api/serializers.py): `backend/stocks/api/serializers.py`
- [API Routes](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/stocks/api/urls.py): `backend/stocks/api/urls.py`
- [JWT Authentication](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/config/settings.py): `backend/config/settings.py`
- [OpenAPI Docs](https://github.com/winillnwang/us-stock-intelligence-platform/blob/master/backend/config/urls.py): `backend/config/urls.py`

### Other components

- **API Client**
- **Alpha Vantage**

## Connections

- Update Command → Stock Models: looks up (evidence: `backend/stocks/management/commands/update_stock_prices.py`)
- Update Command → Price Service: updates prices (evidence: `backend/stocks/management/commands/update_stock_prices.py`)
- Fetch Script → Stock Config: loads settings (evidence: `scripts/fetch_stock_data.py`)
- Fetch Script → Price Service: fetches and cleans (evidence: `scripts/fetch_stock_data.py`)
- Price Service → Alpha Vantage: requests prices (evidence: `backend/stocks/services/alpha_vantage.py`)
- Price Service → Price Validation: transforms data (evidence: `backend/stocks/services/alpha_vantage.py`)
- Price Service → Price Persistence: saves prices (evidence: `backend/stocks/services/alpha_vantage.py`)
- Price Persistence → Stock Models: writes records (evidence: `backend/stocks/services/alpha_vantage.py`)
- Stock Models → MySQL Data: persists via ORM (evidence: `README.md`)
- Search and Analytics → Stock Models: queries stocks (evidence: `backend/stocks/views.py`)
- Search and Analytics → Stock Pages: renders pages (evidence: `backend/stocks/views.py`)
- API Routes → Stock API: routes requests (evidence: `backend/stocks/api/urls.py`)
- Stock API → Stock Models: queries records (evidence: `backend/stocks/api/views.py`)
- Stock API → API Serializers: serializes results (evidence: `backend/stocks/api/views.py`)
- Stock API → JWT Authentication: requires authentication (evidence: `backend/stocks/api/views.py`)
- API Client → Stock API: requests data (evidence: `README.md`)
- API Client → JWT Authentication: obtains tokens (evidence: `README.md`)
- API Client → OpenAPI Docs: views documentation (evidence: `README.md`)
- Stock Admin → Stock Models: manages records (evidence: `backend/stocks/admin.py`)
