# yaubernice/portfolytix architecture

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

- Interactive diagram: https://gitdiagram.com/yaubernice/portfolytix
- Repository: https://github.com/yaubernice/portfolytix
- Video tour (about a minute): https://gitdiagram.com/yaubernice/portfolytix/video

## Overview

Portfolytix is a personal portfolio workspace: users manage portfolios and transactions, then view ledger-derived holdings and portfolio analytics, with screening, market data, live quotes, and evidence-grounded explanations as supporting capabilities. The dashboard calls a FastAPI API; services apply domain logic over PostgreSQL and Redis. The README documents the main request and background-job flows. Some feature internals are unsampled, so those branches are shown only where documentation supports their connections.

Main entry points: [`app/main.py`](https://github.com/yaubernice/portfolytix/blob/main/app/main.py) (FastAPI application), [`app/jobs/market_data_job.py`](https://github.com/yaubernice/portfolytix/blob/main/app/jobs/market_data_job.py) (Market-data job), [`app/services/ledger_service.py`](https://github.com/yaubernice/portfolytix/blob/main/app/services/ledger_service.py) (Transaction ledger), [`app/db/models/__init__.py`](https://github.com/yaubernice/portfolytix/blob/main/app/db/models/__init__.py) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interfaces"]
  node_dashboard["Next.js dashboard<br/>[page.js]"]
  node_api_client["Web API client<br/>[api.js]"]
end

subgraph group_api["API and domain"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_portfolio["Portfolio service"]
  node_transactions["Transaction ledger<br/>[ledger_service.py]"]
  node_holdings["Derived holdings<br/>[holdings.py]"]
  node_analytics["Portfolio analytics"]
  node_screening["Fundamental screening"]
  node_research["Research suggestions"]
end

subgraph group_data["Persistence and cache"]
  node_quote_store["Live quote store<br/>[store.py]"]
  node_repositories["Data repositories"]
  node_postgres[("PostgreSQL<br/>[__init__.py]")]
  node_redis_cache[("Redis cache<br/>[cache.py]")]
  node_redis_quotes[("Redis quote state<br/>[store.py]")]
end

subgraph group_market["Market and assistant"]
  node_assistant["Evidence assistant"]
  node_evidence["Evidence construction<br/>[evidence.py]"]
  node_scheduler["Market-data scheduler<br/>[scheduler.py]"]
  node_ingestion["Market-data job<br/>[market_data_job.py]"]
  node_market_provider["Market-data providers<br/>[factory.py]"]
  node_quote_worker["Live quote worker<br/>[quote_worker.py]"]
end

node_user(("Investor"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_fastapi
node_fastapi -->|"authenticates"| node_auth
node_fastapi -->|"routes requests"| node_portfolio
node_portfolio -->|"reads and writes"| node_repositories
node_transactions -->|"stores fills"| node_postgres
node_transactions -->|"queues invalidation"| node_redis_cache
node_portfolio -->|"records fills"| node_transactions
node_holdings -->|"derives quantities"| node_transactions
node_analytics -->|"loads portfolio data"| node_repositories
node_analytics -->|"reads and caches"| node_redis_cache
node_screening -->|"queries fundamentals"| node_postgres
node_research -->|"reads snapshots"| node_postgres
node_assistant -->|"loads evidence"| node_analytics
node_assistant -->|"grounds answers"| node_evidence
node_scheduler -->|"schedules job"| node_ingestion
node_ingestion -->|"fetches market data"| node_market_provider
node_ingestion -->|"upserts prices"| node_postgres
node_ingestion -->|"invalidates prices"| node_redis_cache
node_quote_worker -->|"publishes quotes"| node_quote_store
node_quote_store -->|"stores and broadcasts"| node_redis_quotes
node_fastapi -->|"serves live quotes"| node_redis_quotes

click node_dashboard "https://github.com/yaubernice/portfolytix/blob/main/web/app/portfolio/page.js"
click node_api_client "https://github.com/yaubernice/portfolytix/blob/main/web/lib/api.js"
click node_fastapi "https://github.com/yaubernice/portfolytix/blob/main/app/main.py"
click node_auth "https://github.com/yaubernice/portfolytix/blob/main/app/services/auth_service.py"
click node_portfolio "https://github.com/yaubernice/portfolytix/blob/main/app/services/portfolio_service.py"
click node_transactions "https://github.com/yaubernice/portfolytix/blob/main/app/services/ledger_service.py"
click node_holdings "https://github.com/yaubernice/portfolytix/blob/main/app/services/holdings.py"
click node_analytics "https://github.com/yaubernice/portfolytix/blob/main/app/services/analytics_service.py"
click node_screening "https://github.com/yaubernice/portfolytix/blob/main/app/services/screening_service.py"
click node_research "https://github.com/yaubernice/portfolytix/blob/main/app/services/research_service.py"
click node_assistant "https://github.com/yaubernice/portfolytix/blob/main/app/services/assistant_service.py"
click node_evidence "https://github.com/yaubernice/portfolytix/blob/main/app/ai/evidence.py"
click node_scheduler "https://github.com/yaubernice/portfolytix/blob/main/app/jobs/scheduler.py"
click node_ingestion "https://github.com/yaubernice/portfolytix/blob/main/app/jobs/market_data_job.py"
click node_market_provider "https://github.com/yaubernice/portfolytix/blob/main/app/market_data/factory.py"
click node_quote_worker "https://github.com/yaubernice/portfolytix/blob/main/app/workers/quote_worker.py"
click node_quote_store "https://github.com/yaubernice/portfolytix/blob/main/app/quotes/store.py"
click node_repositories "https://github.com/yaubernice/portfolytix/blob/main/app/repositories/portfolio_repository.py"
click node_postgres "https://github.com/yaubernice/portfolytix/blob/main/app/db/models/__init__.py"
click node_redis_cache "https://github.com/yaubernice/portfolytix/blob/main/app/core/cache.py"
click node_redis_quotes "https://github.com/yaubernice/portfolytix/blob/main/app/quotes/store.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_dashboard,node_api_client toneBlue
class node_fastapi,node_auth,node_portfolio,node_transactions,node_holdings,node_analytics,node_screening,node_research toneAmber
class node_quote_store,node_repositories,node_postgres,node_redis_cache,node_redis_quotes toneMint
class node_assistant,node_evidence,node_scheduler,node_ingestion,node_market_provider,node_quote_worker toneRose
class node_user toneIndigo
```

## Components

### User interfaces

- [Next.js dashboard](https://github.com/yaubernice/portfolytix/blob/main/web/app/portfolio/page.js): `web/app/portfolio/page.js`
- [Web API client](https://github.com/yaubernice/portfolytix/blob/main/web/lib/api.js): `web/lib/api.js`

### API and domain

- [FastAPI application](https://github.com/yaubernice/portfolytix/blob/main/app/main.py): `app/main.py`
- [Authentication](https://github.com/yaubernice/portfolytix/blob/main/app/services/auth_service.py): `app/services/auth_service.py`
- [Portfolio service](https://github.com/yaubernice/portfolytix/blob/main/app/services/portfolio_service.py): `app/services/portfolio_service.py`
- [Transaction ledger](https://github.com/yaubernice/portfolytix/blob/main/app/services/ledger_service.py): `app/services/ledger_service.py`
- [Derived holdings](https://github.com/yaubernice/portfolytix/blob/main/app/services/holdings.py): `app/services/holdings.py`
- [Portfolio analytics](https://github.com/yaubernice/portfolytix/blob/main/app/services/analytics_service.py): `app/services/analytics_service.py`
- [Fundamental screening](https://github.com/yaubernice/portfolytix/blob/main/app/services/screening_service.py): `app/services/screening_service.py`
- [Research suggestions](https://github.com/yaubernice/portfolytix/blob/main/app/services/research_service.py): `app/services/research_service.py`

### Persistence and cache

- [Live quote store](https://github.com/yaubernice/portfolytix/blob/main/app/quotes/store.py): `app/quotes/store.py`
- [Data repositories](https://github.com/yaubernice/portfolytix/blob/main/app/repositories/portfolio_repository.py): `app/repositories/portfolio_repository.py`
- [PostgreSQL](https://github.com/yaubernice/portfolytix/blob/main/app/db/models/__init__.py): `app/db/models/__init__.py`
- [Redis cache](https://github.com/yaubernice/portfolytix/blob/main/app/core/cache.py): `app/core/cache.py`
- [Redis quote state](https://github.com/yaubernice/portfolytix/blob/main/app/quotes/store.py): `app/quotes/store.py`

### Market and assistant

- [Evidence assistant](https://github.com/yaubernice/portfolytix/blob/main/app/services/assistant_service.py): `app/services/assistant_service.py`
- [Evidence construction](https://github.com/yaubernice/portfolytix/blob/main/app/ai/evidence.py): `app/ai/evidence.py`
- [Market-data scheduler](https://github.com/yaubernice/portfolytix/blob/main/app/jobs/scheduler.py): `app/jobs/scheduler.py`
- [Market-data job](https://github.com/yaubernice/portfolytix/blob/main/app/jobs/market_data_job.py): `app/jobs/market_data_job.py`
- [Market-data providers](https://github.com/yaubernice/portfolytix/blob/main/app/market_data/factory.py): `app/market_data/factory.py`
- [Live quote worker](https://github.com/yaubernice/portfolytix/blob/main/app/workers/quote_worker.py): `app/workers/quote_worker.py`

### Other components

- **Investor**

## Connections

- Investor → Next.js dashboard: uses (evidence: `README.md`)
- Next.js dashboard → Web API client: requests data (evidence: `web/app/portfolio/page.js`)
- Web API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Authentication: authenticates (evidence: `README.md`)
- FastAPI application → Portfolio service: routes requests (evidence: `README.md`)
- Portfolio service → Data repositories: reads and writes (evidence: `README.md`)
- Transaction ledger → PostgreSQL: stores fills (evidence: `README.md`)
- Transaction ledger → Redis cache: queues invalidation (evidence: `README.md`)
- Portfolio service → Transaction ledger: records fills (evidence: `README.md`)
- Derived holdings → Transaction ledger: derives quantities (evidence: `README.md`)
- Portfolio analytics → Data repositories: loads portfolio data (evidence: `app/services/analytics_service.py`)
- Portfolio analytics → Redis cache: reads and caches (evidence: `README.md`)
- Fundamental screening → PostgreSQL: queries fundamentals (evidence: `README.md`)
- Research suggestions → PostgreSQL: reads snapshots (evidence: `app/services/research_service.py`)
- Evidence assistant → Portfolio analytics: loads evidence (evidence: `README.md`)
- Evidence assistant → Evidence construction: grounds answers (evidence: `app/ai/evidence.py`)
- Market-data scheduler → Market-data job: schedules job (evidence: `README.md`)
- Market-data job → Market-data providers: fetches market data (evidence: `app/jobs/market_data_job.py`)
- Market-data job → PostgreSQL: upserts prices (evidence: `README.md`)
- Market-data job → Redis cache: invalidates prices (evidence: `README.md`)
- Live quote worker → Live quote store: publishes quotes (evidence: `app/workers/quote_worker.py`)
- Live quote store → Redis quote state: stores and broadcasts (evidence: `README.md`)
- FastAPI application → Redis quote state: serves live quotes (evidence: `README.md`)
