# derrickvericho/intelflow architecture

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

- Interactive diagram: https://gitdiagram.com/derrickvericho/intelflow
- Repository: https://github.com/derrickvericho/intelflow

## Overview

IntelFlow is an IDX-stock market-intelligence application. Users search for a ticker and open IntelScore or shareholder research; the backend gathers provider data, builds flow and fundamental evidence, calculates scores, and returns research responses. It also exposes separate flow, price-history, shareholder, and broker-series endpoints. The README documents Redis-backed caching and the Sectors API dependency. Some frontend feature and backend gateway internals are unsampled, so their detailed wiring is not inferred.

Main entry points: [`src/frontend/app/App.tsx`](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/app/App.tsx) (Routes and shell), [`src/backend/services/research.py`](https://github.com/derrickvericho/intelflow/blob/main/src/backend/services/research.py) (Research service), [`src/backend/sectors/cached.py`](https://github.com/derrickvericho/intelflow/blob/main/src/backend/sectors/cached.py) (Cached gateway), [`src/backend/api/routes.py`](https://github.com/derrickvericho/intelflow/blob/main/src/backend/api/routes.py) (Stock API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app["Routes and shell<br/>[App.tsx]"]
  node_search["Ticker search<br/>[SymbolSearch.tsx]"]
  node_intelpage["IntelScore page<br/>[IntelScorePage.tsx]"]
  node_home["Home research<br/>[HomePage.tsx]"]
  node_sharesearch["Shareholder search"]
  node_sharepage["Shareholder page"]
  node_flowui["Flow feature<br/>[FlowSection.tsx]"]
  node_fundamentalsui["Fundamentals feature<br/>[Fundamentals.tsx]"]
  node_scoresui["Score feature<br/>[Scores.tsx]"]
  node_trendsui["Trends feature<br/>[Trends.tsx]"]
  node_shareholdersui["Shareholder composition<br/>[composition.ts]"]
  node_api_client["HTTP client<br/>[client.ts]"]
end

subgraph group_api["API and research"]
  node_routes["Stock API routes<br/>[routes.py]"]
  node_service["Research service<br/>[research.py]"]
  node_scoring["Score calculations"]
  node_models["Research models"]
end

subgraph group_integrations["Data integrations"]
  node_cached_gateway["Cached gateway<br/>[cached.py]"]
  node_gateway["Provider gateway<br/>[gateway.py]"]
  node_sectors_client["Sectors client<br/>[client.py]"]
  node_cache_store["Redis cache<br/>[store.py]"]
end

subgraph group_runtime["Application runtime"]
  node_main["App assembly<br/>[main.py]"]
end

node_user(("Investor"))
node_sectors_api{{"Sectors API"}}
node_redis[("Redis")]
node_browser(("Web browser"))

node_user -->|"enters ticker"| node_search
node_search -->|"navigates to"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_intelpage
node_app -->|"routes to"| node_sharesearch
node_app -->|"routes to"| node_sharepage
node_browser -->|"requests data"| node_api_client
node_api_client -->|"HTTP requests"| node_routes
node_main -->|"mounts"| node_routes
node_main -->|"constructs"| node_service
node_routes -->|"calls use cases"| node_service
node_service -->|"requests market data"| node_cached_gateway
node_cached_gateway -->|"delegates misses"| node_gateway
node_cached_gateway -->|"reads and writes"| node_cache_store
node_gateway -->|"calls provider client"| node_sectors_client
node_sectors_client -->|"fetches data"| node_sectors_api
node_cache_store -->|"reads and writes"| node_redis
node_service -->|"calculates scores"| node_scoring
node_service -->|"builds responses"| node_models

click node_app "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/app/App.tsx"
click node_search "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/components/SymbolSearch.tsx"
click node_intelpage "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/pages/IntelScorePage.tsx"
click node_home "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/pages/HomePage.tsx"
click node_sharesearch "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/pages/ShareholdersSearchPage.tsx"
click node_sharepage "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/pages/ShareholdersPage.tsx"
click node_flowui "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/features/flow/FlowSection.tsx"
click node_fundamentalsui "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/features/fundamentals/Fundamentals.tsx"
click node_scoresui "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/features/scores/Scores.tsx"
click node_trendsui "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/features/trends/Trends.tsx"
click node_shareholdersui "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/features/shareholders/composition.ts"
click node_api_client "https://github.com/derrickvericho/intelflow/blob/main/src/frontend/api/client.ts"
click node_routes "https://github.com/derrickvericho/intelflow/blob/main/src/backend/api/routes.py"
click node_service "https://github.com/derrickvericho/intelflow/blob/main/src/backend/services/research.py"
click node_scoring "https://github.com/derrickvericho/intelflow/tree/main/src/backend/scoring"
click node_models "https://github.com/derrickvericho/intelflow/tree/main/src/backend/models"
click node_cached_gateway "https://github.com/derrickvericho/intelflow/blob/main/src/backend/sectors/cached.py"
click node_gateway "https://github.com/derrickvericho/intelflow/blob/main/src/backend/sectors/gateway.py"
click node_sectors_client "https://github.com/derrickvericho/intelflow/blob/main/src/backend/sectors/client.py"
click node_cache_store "https://github.com/derrickvericho/intelflow/blob/main/src/backend/cache/store.py"
click node_main "https://github.com/derrickvericho/intelflow/blob/main/src/backend/main.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_app,node_search,node_intelpage,node_home,node_sharesearch,node_sharepage,node_flowui,node_fundamentalsui,node_scoresui,node_trendsui,node_shareholdersui,node_api_client,node_browser toneBlue
class node_routes,node_service,node_scoring,node_models,node_redis toneAmber
class node_cached_gateway,node_gateway,node_sectors_client,node_cache_store,node_sectors_api toneMint
class node_main toneRose
class node_user toneIndigo
```

## Components

### Frontend

- [Routes and shell](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/app/App.tsx): `src/frontend/app/App.tsx`
- [Ticker search](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/components/SymbolSearch.tsx): `src/frontend/components/SymbolSearch.tsx`
- [IntelScore page](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/pages/IntelScorePage.tsx): `src/frontend/pages/IntelScorePage.tsx`
- [Home research](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/pages/HomePage.tsx): `src/frontend/pages/HomePage.tsx`
- [Shareholder search](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/pages/ShareholdersSearchPage.tsx): `src/frontend/pages/ShareholdersSearchPage.tsx`
- [Shareholder page](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/pages/ShareholdersPage.tsx): `src/frontend/pages/ShareholdersPage.tsx`
- [Flow feature](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/features/flow/FlowSection.tsx): `src/frontend/features/flow/FlowSection.tsx`
- [Fundamentals feature](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/features/fundamentals/Fundamentals.tsx): `src/frontend/features/fundamentals/Fundamentals.tsx`
- [Score feature](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/features/scores/Scores.tsx): `src/frontend/features/scores/Scores.tsx`
- [Trends feature](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/features/trends/Trends.tsx): `src/frontend/features/trends/Trends.tsx`
- [Shareholder composition](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/features/shareholders/composition.ts): `src/frontend/features/shareholders/composition.ts`
- [HTTP client](https://github.com/derrickvericho/intelflow/blob/main/src/frontend/api/client.ts): `src/frontend/api/client.ts`

### API and research

- [Stock API routes](https://github.com/derrickvericho/intelflow/blob/main/src/backend/api/routes.py): `src/backend/api/routes.py`
- [Research service](https://github.com/derrickvericho/intelflow/blob/main/src/backend/services/research.py): `src/backend/services/research.py`
- [Score calculations](https://github.com/derrickvericho/intelflow/tree/main/src/backend/scoring): `src/backend/scoring`
- [Research models](https://github.com/derrickvericho/intelflow/tree/main/src/backend/models): `src/backend/models`

### Data integrations

- [Cached gateway](https://github.com/derrickvericho/intelflow/blob/main/src/backend/sectors/cached.py): `src/backend/sectors/cached.py`
- [Provider gateway](https://github.com/derrickvericho/intelflow/blob/main/src/backend/sectors/gateway.py): `src/backend/sectors/gateway.py`
- [Sectors client](https://github.com/derrickvericho/intelflow/blob/main/src/backend/sectors/client.py): `src/backend/sectors/client.py`
- [Redis cache](https://github.com/derrickvericho/intelflow/blob/main/src/backend/cache/store.py): `src/backend/cache/store.py`

### Application runtime

- [App assembly](https://github.com/derrickvericho/intelflow/blob/main/src/backend/main.py): `src/backend/main.py`

### Other components

- **Investor**
- **Sectors API**
- **Redis**
- **Web browser**

## Connections

- Investor → Ticker search: enters ticker
- Ticker search → Routes and shell: navigates to
- Routes and shell → Home research: routes to
- Routes and shell → IntelScore page: routes to
- Routes and shell → Shareholder search: routes to
- Routes and shell → Shareholder page: routes to
- Web browser → HTTP client: requests data
- HTTP client → Stock API routes: HTTP requests
- App assembly → Stock API routes: mounts
- App assembly → Research service: constructs
- Stock API routes → Research service: calls use cases
- Research service → Cached gateway: requests market data
- Cached gateway → Provider gateway: delegates misses
- Cached gateway → Redis cache: reads and writes
- Provider gateway → Sectors client: calls provider client
- Sectors client → Sectors API: fetches data
- Redis cache → Redis: reads and writes
- Research service → Score calculations: calculates scores
- Research service → Research models: builds responses