# ashik-z/microvest architecture

> Architecture diagram of the GitHub repository ashik-z/microvest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashik-z/microvest
- Repository: https://github.com/ashik-z/microvest

## Overview

1. **Overall shape**  
   Microvest is a **server-rendered FastAPI application** rather than a separate frontend/backend split. Browser requests hit FastAPI routes, which fetch data from MySQL, call market-data services, and render **Jinja2 templates** back to the client.

2. **Request entrypoint and app wiring**  
   `backend/main.py` is the application bootstrap. It likely wires the FastAPI app, mounts routers, configures templates/static assets, and connects middleware/session handling. This is the top-level composition point for the whole system.

3. **Configuration and runtime boundaries**  
   `backend/config.py` centralizes environment-driven settings such as MySQL connection values, the secret key, and debug mode. That keeps deployment concerns separate from business logic and makes the app portable across environments.

4. **Persistence layer**  
   `backend/database.py` and `backend/models.py` define the SQLAlchemy boundary to MySQL. The data model probably includes users, watchlist entries, portfolio holdings, and transaction records, since those are the core domain objects exposed by the README features.

5. **Authentication subsystem**  
   `backend/routers/auth.py` and `backend/services/auth_service.py` handle registration, login, and session-backed access control. The README indicates **secure session cookies**, **itsdangerous**, and **bcrypt/password hashing**, so auth is stateful and server-managed rather than token-only API auth.

6. **Dependency injection and request context**  
   `backend/dependencies.py` is the glue layer for common request-scoped concerns such as obtaining a database session and resolving the currently authenticated user. This is an important architectural boundary because it keeps routers thin and consistent.

7. **Watchlist and portfolio flows**  
   `backend/routers/watchlist.py` and `backend/routers/portfolio.py` drive the two main user workflows: tracking symbols and simulating buy/sell activity. These routes likely orchestrate both database persistence and live price lookup before rendering the corresponding page.

8. **Market-data service layer**  
   `backend/services/stock_service.py` is the external-data boundary. The README says it uses **yfinance** with **60-second caching**, so this service isolates market-price retrieval from the rest of the app and reduces repeated upstream calls.

9. **Dashboard aggregation**  
   `backend/routers/dashboard.py` is the read-heavy summary view. It likely combines portfolio valuation, profit/loss, watchlist counts, and recent transactions into a single page, making it a presentation-level aggregation over multiple database tables and stock-service calls.

10. **Inflation subsystem**  
   `backend/routers/inflation.py` and `backend/services/inflation_service.py` are a separate analytics slice from the core trading/watchlist flows. This appears to provide macro/inflation context as an additional dashboard-style view, probably backed by an external data source distinct from the stock quotes.

11. **Template layer**  
   `backend/templates/` contains page templates for login, registration, dashboard, watchlist, portfolio, and inflation, all extending `base.html`. This confirms the app is **multi-page, server-rendered**, with Tailwind/Alpine used for styling and light interactivity rather than a SPA framework.

12. **Typical data flow**  
   A request usually flows as: browser → router → dependency resolution (DB/user) → service layer → MySQL and/or external market data → template rendering → browser response. The important architectural distinction is that routers coordinate, services encapsulate business/external logic, and models/database handle persistence.

13. **External dependencies that shape the design**  
   The main external systems are **MySQL** for persistence and **yfinance** for live stock data. Their presence drives the separation between database models, cached market-data service logic, and the server-rendered pages that present the results.

Main entry points: [`backend/main.py`](https://github.com/ashik-z/microvest/blob/main/backend/main.py) (App bootstrap), [`backend/templates/base.html`](https://github.com/ashik-z/microvest/blob/main/backend/templates/base.html) (Base layout), [`backend/database.py`](https://github.com/ashik-z/microvest/blob/main/backend/database.py) (DB session), [`backend/routers/auth.py`](https://github.com/ashik-z/microvest/blob/main/backend/routers/auth.py) (Auth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend App"]
  node_main["App bootstrap<br/>FastAPI entrypoint<br/>[main.py]"]
  node_config["Settings<br/>runtime config<br/>[config.py]"]
  node_deps["Dependencies<br/>request context<br/>[dependencies.py]"]
  node_auth_router["Auth routes<br/>router<br/>[auth.py]"]
  node_dashboard_router["Dashboard<br/>router<br/>[dashboard.py]"]
  node_watchlist_router["Watchlist<br/>router<br/>[watchlist.py]"]
  node_portfolio_router["Portfolio<br/>router<br/>[portfolio.py]"]
  node_inflation_router["Inflation<br/>router<br/>[inflation.py]"]
  node_auth_service["Auth service<br/>session auth<br/>[auth_service.py]"]
  node_stock_service["Stock service<br/>market data<br/>[stock_service.py]"]
  node_inflation_service["Inflation service<br/>analytics data"]
end

subgraph group_storage["Data Layer"]
  node_database[("DB session<br/>SQLAlchemy<br/>[database.py]")]
  node_models["Domain models<br/>ORM models<br/>[models.py]"]
end

subgraph group_views["Templates"]
  node_base_tpl["Base layout<br/>Jinja2 template<br/>[base.html]"]
  node_login_tpl["Login page<br/>Jinja2 template<br/>[login.html]"]
  node_register_tpl["Register page<br/>Jinja2 template<br/>[register.html]"]
  node_dashboard_tpl["Dashboard page<br/>Jinja2 template<br/>[dashboard.html]"]
  node_watchlist_tpl["Watchlist page<br/>Jinja2 template<br/>[watchlist.html]"]
  node_portfolio_tpl["Portfolio page<br/>Jinja2 template<br/>[portfolio.html]"]
  node_inflation_tpl["Inflation page<br/>Jinja2 template<br/>[inflation.html]"]
end

subgraph group_external["External Systems"]
  node_mysql[("MySQL<br/>relational DB")]
  node_yfinance(("yfinance<br/>market data API"))
end

node_main -->|"loads"| node_config
node_main -->|"wires"| node_deps
node_main -->|"mounts"| node_auth_router
node_main -->|"mounts"| node_dashboard_router
node_main -->|"mounts"| node_watchlist_router
node_main -->|"mounts"| node_portfolio_router
node_main -->|"mounts"| node_inflation_router
node_main -->|"configures"| node_base_tpl
node_auth_router -->|"uses"| node_auth_service
node_auth_router -->|"renders"| node_login_tpl
node_auth_router -->|"renders"| node_register_tpl
node_dashboard_router -->|"uses"| node_stock_service
node_dashboard_router -->|"renders"| node_dashboard_tpl
node_watchlist_router -->|"uses"| node_stock_service
node_watchlist_router -->|"renders"| node_watchlist_tpl
node_portfolio_router -->|"uses"| node_stock_service
node_portfolio_router -->|"renders"| node_portfolio_tpl
node_inflation_router -->|"uses"| node_inflation_service
node_inflation_router -->|"renders"| node_inflation_tpl
node_auth_service -->|"queries"| node_database
node_dashboard_router -->|"queries"| node_database
node_watchlist_router -->|"queries"| node_database
node_portfolio_router -->|"queries"| node_database
node_inflation_service -.->|"optional read"| node_database
node_database -->|"maps to"| node_models
node_stock_service -->|"fetches from"| node_yfinance
node_dashboard_tpl -->|"extends"| node_base_tpl
node_login_tpl -->|"extends"| node_base_tpl
node_register_tpl -->|"extends"| node_base_tpl
node_watchlist_tpl -->|"extends"| node_base_tpl
node_portfolio_tpl -->|"extends"| node_base_tpl
node_inflation_tpl -->|"extends"| node_base_tpl

click node_main "https://github.com/ashik-z/microvest/blob/main/backend/main.py"
click node_config "https://github.com/ashik-z/microvest/blob/main/backend/config.py"
click node_deps "https://github.com/ashik-z/microvest/blob/main/backend/dependencies.py"
click node_auth_router "https://github.com/ashik-z/microvest/blob/main/backend/routers/auth.py"
click node_dashboard_router "https://github.com/ashik-z/microvest/blob/main/backend/routers/dashboard.py"
click node_watchlist_router "https://github.com/ashik-z/microvest/blob/main/backend/routers/watchlist.py"
click node_portfolio_router "https://github.com/ashik-z/microvest/blob/main/backend/routers/portfolio.py"
click node_inflation_router "https://github.com/ashik-z/microvest/blob/main/backend/routers/inflation.py"
click node_auth_service "https://github.com/ashik-z/microvest/blob/main/backend/services/auth_service.py"
click node_stock_service "https://github.com/ashik-z/microvest/blob/main/backend/services/stock_service.py"
click node_inflation_service "https://github.com/ashik-z/microvest/blob/main/backend/services/inflation_service.py"
click node_database "https://github.com/ashik-z/microvest/blob/main/backend/database.py"
click node_models "https://github.com/ashik-z/microvest/blob/main/backend/models.py"
click node_base_tpl "https://github.com/ashik-z/microvest/blob/main/backend/templates/base.html"
click node_login_tpl "https://github.com/ashik-z/microvest/blob/main/backend/templates/login.html"
click node_register_tpl "https://github.com/ashik-z/microvest/blob/main/backend/templates/register.html"
click node_dashboard_tpl "https://github.com/ashik-z/microvest/blob/main/backend/templates/dashboard.html"
click node_watchlist_tpl "https://github.com/ashik-z/microvest/blob/main/backend/templates/watchlist.html"
click node_portfolio_tpl "https://github.com/ashik-z/microvest/blob/main/backend/templates/portfolio.html"
click node_inflation_tpl "https://github.com/ashik-z/microvest/blob/main/backend/templates/inflation.html"

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_main,node_config,node_deps,node_auth_router,node_dashboard_router,node_watchlist_router,node_portfolio_router,node_inflation_router,node_auth_service,node_stock_service,node_inflation_service toneBlue
class node_database,node_models toneAmber
class node_base_tpl,node_login_tpl,node_register_tpl,node_dashboard_tpl,node_watchlist_tpl,node_portfolio_tpl,node_inflation_tpl toneMint
class node_mysql,node_yfinance toneRose
```

## Components

### Backend App

FastAPI application wiring, routes, services, and shared runtime code.

- [App bootstrap](https://github.com/ashik-z/microvest/blob/main/backend/main.py): FastAPI entrypoint · Creates and configures the application, routers, templates, and middleware. · `backend/main.py`
- [Settings](https://github.com/ashik-z/microvest/blob/main/backend/config.py): runtime config · Environment-driven configuration such as DB credentials, secret key, and debug mode. · `backend/config.py`
- [Dependencies](https://github.com/ashik-z/microvest/blob/main/backend/dependencies.py): request context · Shared request-scoped helpers for database sessions and current user resolution. · `backend/dependencies.py`
- [Auth routes](https://github.com/ashik-z/microvest/blob/main/backend/routers/auth.py): router · Registration, login, logout, and session-based access control endpoints. · `backend/routers/auth.py`
- [Dashboard](https://github.com/ashik-z/microvest/blob/main/backend/routers/dashboard.py): router · Aggregated summary view combining portfolio, watchlist, and transaction data. · `backend/routers/dashboard.py`
- [Watchlist](https://github.com/ashik-z/microvest/blob/main/backend/routers/watchlist.py): router · Routes for tracking symbols and displaying watchlist state. · `backend/routers/watchlist.py`
- [Portfolio](https://github.com/ashik-z/microvest/blob/main/backend/routers/portfolio.py): router · Routes for buy/sell simulation and portfolio views. · `backend/routers/portfolio.py`
- [Inflation](https://github.com/ashik-z/microvest/blob/main/backend/routers/inflation.py): router · Routes for macro and inflation analytics pages. · `backend/routers/inflation.py`
- [Auth service](https://github.com/ashik-z/microvest/blob/main/backend/services/auth_service.py): session auth · Implements user authentication, password handling, and login/session logic. · `backend/services/auth_service.py`
- [Stock service](https://github.com/ashik-z/microvest/blob/main/backend/services/stock_service.py): market data · Fetches live stock prices with caching to reduce upstream calls. · `backend/services/stock_service.py`
- [Inflation service](https://github.com/ashik-z/microvest/blob/main/backend/services/inflation_service.py): analytics data · Loads inflation or macroeconomic data for the analytics views. · `backend/services/inflation_service.py`

### Data Layer

Database boundary and domain models persisted in MySQL.

- [DB session](https://github.com/ashik-z/microvest/blob/main/backend/database.py): SQLAlchemy · Database engine/session boundary used by the application to reach MySQL. · `backend/database.py`
- [Domain models](https://github.com/ashik-z/microvest/blob/main/backend/models.py): ORM models · SQLAlchemy models for users, watchlists, portfolios, and transactions. · `backend/models.py`

### Templates

Server-rendered Jinja2 pages returned to the browser.

- [Base layout](https://github.com/ashik-z/microvest/blob/main/backend/templates/base.html): Jinja2 template · Shared page shell extended by all rendered views. · `backend/templates/base.html`
- [Login page](https://github.com/ashik-z/microvest/blob/main/backend/templates/login.html): Jinja2 template · Sign-in form and authentication page. · `backend/templates/login.html`
- [Register page](https://github.com/ashik-z/microvest/blob/main/backend/templates/register.html): Jinja2 template · User registration form. · `backend/templates/register.html`
- [Dashboard page](https://github.com/ashik-z/microvest/blob/main/backend/templates/dashboard.html): Jinja2 template · Server-rendered portfolio summary page. · `backend/templates/dashboard.html`
- [Watchlist page](https://github.com/ashik-z/microvest/blob/main/backend/templates/watchlist.html): Jinja2 template · Server-rendered symbol tracking page. · `backend/templates/watchlist.html`
- [Portfolio page](https://github.com/ashik-z/microvest/blob/main/backend/templates/portfolio.html): Jinja2 template · Server-rendered holdings and trade page. · `backend/templates/portfolio.html`
- [Inflation page](https://github.com/ashik-z/microvest/blob/main/backend/templates/inflation.html): Jinja2 template · Server-rendered macro and inflation analytics page. · `backend/templates/inflation.html`

### External Systems

Outside services and infrastructure the app depends on.

- **MySQL**: relational DB · Primary persistence store for application data.
- **yfinance**: market data API · External source for live stock quotes and related market data.

## Connections

- App bootstrap → Settings: loads · Application startup reads environment settings.
- App bootstrap → Dependencies: wires · Registers shared dependency helpers.
- App bootstrap → Auth routes: mounts · Adds authentication routes to the app.
- App bootstrap → Dashboard: mounts · Adds dashboard routes to the app.
- App bootstrap → Watchlist: mounts · Adds watchlist routes to the app.
- App bootstrap → Portfolio: mounts · Adds portfolio routes to the app.
- App bootstrap → Inflation: mounts · Adds inflation routes to the app.
- App bootstrap → Base layout: configures · Sets up template rendering for responses.
- Auth routes → Auth service: uses · Delegates authentication logic to the service layer.
- Auth routes → Login page: renders · Returns the login page.
- Auth routes → Register page: renders · Returns the registration page.
- Dashboard → Stock service: uses · Fetches live market data for summary calculations.
- Dashboard → Dashboard page: renders · Returns the dashboard page.
- Watchlist → Stock service: uses · Looks up current prices for tracked symbols.
- Watchlist → Watchlist page: renders · Returns the watchlist page.
- Portfolio → Stock service: uses · Uses quotes for valuation and trade simulation.
- Portfolio → Portfolio page: renders · Returns the portfolio page.
- Inflation → Inflation service: uses · Loads inflation analytics data.
- Inflation → Inflation page: renders · Returns the inflation page.
- Auth service → DB session: queries · Reads and writes authentication-related state.
- Dashboard → DB session: queries · Reads persisted portfolio and activity data.
- Watchlist → DB session: queries · Reads and updates watchlist entries.
- Portfolio → DB session: queries · Reads and updates portfolio and transaction records.
- Inflation service → DB session: optional read · May use persisted settings or cached analytics state.
- DB session → Domain models: maps to · ORM layer defines persisted entities.
- Stock service → yfinance: fetches from · Retrieves market data from the external provider.
- Dashboard page → Base layout: extends · Shares the common layout.
- Login page → Base layout: extends · Shares the common layout.
- Register page → Base layout: extends · Shares the common layout.
- Watchlist page → Base layout: extends · Shares the common layout.
- Portfolio page → Base layout: extends · Shares the common layout.
- Inflation page → Base layout: extends · Shares the common layout.