# ckeen302/senior_design_project architecture

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

- Interactive diagram: https://gitdiagram.com/ckeen302/senior_design_project
- Repository: https://github.com/ckeen302/senior_design_project

## Overview

InsiderPulse is a cross-platform SEC Form 4 tracker. Users authenticate, browse insider trades and WISI signals, manage a watchlist, and inspect company charts and live prices; searches can import untracked tickers. Separately, scheduled ingestion fetches and parses SEC filings, stores transactions, and emits whale alerts. The README documents database-triggered WISI recalculation and Realtime delivery. Several screen and backend links are documented rather than verified from source excerpts; unsampled implementation details are not inferred.

Main entry points: [`src/navigation/RootNavigator.tsx`](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/navigation/RootNavigator.tsx) (Navigation), [`supabase/functions/fetch-sec-filings/index.ts`](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/fetch-sec-filings/index.ts) (Ingestion endpoint), [`src/lib/api.ts`](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/lib/api.ts) (Data access API), [`supabase/functions/_shared/ingest.ts`](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/ingest.ts) (Ingest pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["InsiderPulse app"]
  node_app["App bootstrap<br/>[App.tsx]"]
  node_auth["Auth state<br/>[authStore.ts]"]
  node_navigation["Navigation<br/>[RootNavigator.tsx]"]
  node_feed["Insider feed<br/>[FeedScreen.tsx]"]
  node_signals["WISI signals<br/>[SignalsScreen.tsx]"]
  node_watchlist["Watchlist"]
  node_company["Company detail"]
  node_settings["Settings<br/>[SettingsScreen.tsx]"]
  node_search["Ticker search"]
end

subgraph group_clientdata["Client data services"]
  node_feedhook["Feed subscription<br/>[useInsiderFeed.ts]"]
  node_watchhook["Watchlist queries<br/>[useWatchlist.ts]"]
  node_companyhook["Company queries<br/>[useCompany.ts]"]
  node_pricehook["Live price hook<br/>[useLivePrice.ts]"]
  node_api["Data access API<br/>[api.ts]"]
  node_cache["Offline query cache<br/>[queryClient.ts]"]
  node_supabaseclient["Supabase client<br/>[supabase.ts]"]
end

subgraph group_ingest["Filing ingestion"]
  node_function["Ingestion endpoint<br/>[index.ts]"]
  node_request["Request validation<br/>[request.ts]"]
  node_pipeline["Ingest pipeline<br/>[ingest.ts]"]
  node_repository["Ingest repository<br/>[repository.ts]"]
  node_edgar["EDGAR client<br/>[edgar.ts]"]
  node_form4["Form 4 parser<br/>[form4.ts]"]
  node_serverfinnhub["Market-cap lookup<br/>[finnhub.ts]"]
  node_push["Whale push alerts<br/>[push.ts]"]
end

subgraph group_platform["Supabase platform"]
  node_database[("Supabase data")]
  node_realtime["Supabase Realtime"]
end

node_user(("App user"))
node_scheduler(("pg_cron"))
node_sec["SEC EDGAR"]
node_finnhub["Finnhub services"]

node_user -->|"opens"| node_app
node_app -->|"initializes"| node_auth
node_app -->|"renders"| node_navigation
node_navigation -->|"offers feed"| node_feed
node_navigation -->|"offers signals"| node_signals
node_navigation -->|"offers watchlist"| node_watchlist
node_navigation -->|"opens detail"| node_company
node_navigation -->|"offers settings"| node_settings
node_feed -.->|"loads trades"| node_feedhook
node_feedhook -->|"fetches feed"| node_api
node_feedhook -->|"subscribes"| node_realtime
node_signals -.->|"loads scores"| node_api
node_watchlist -->|"loads list"| node_watchhook
node_watchhook -->|"reads and updates"| node_api
node_company -->|"loads company"| node_companyhook
node_company -->|"loads price"| node_pricehook
node_companyhook -->|"fetches details"| node_api
node_pricehook -->|"gets live quotes"| node_finnhub
node_search -->|"searches and imports"| node_api
node_search -->|"adds company"| node_watchhook
node_api -->|"queries data"| node_supabaseclient
node_supabaseclient -->|"uses protected API"| node_database
node_app -->|"provides query cache"| node_cache
node_cache -.->|"persists cached results"| node_database
node_scheduler -->|"triggers ingestion"| node_function
node_function -->|"validates request"| node_request
node_function -->|"runs pipeline"| node_pipeline
node_function -->|"creates repository"| node_repository
node_function -->|"sends alerts"| node_push
node_pipeline -->|"fetches filings"| node_edgar
node_pipeline -->|"parses filings"| node_form4
node_pipeline -->|"fetches market cap"| node_serverfinnhub
node_pipeline -->|"reads and upserts"| node_repository
node_edgar -->|"requests filings"| node_sec
node_serverfinnhub -->|"requests market cap"| node_finnhub
node_repository -->|"stores transactions"| node_database
node_database -->|"publishes changes"| node_realtime
node_database -->|"recalculates WISI"| node_database
node_realtime -->|"delivers live inserts"| node_feedhook
node_function -.->|"optional market data"| node_finnhub

click node_app "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/App.tsx"
click node_auth "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/store/authStore.ts"
click node_navigation "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/navigation/RootNavigator.tsx"
click node_feed "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/screens/FeedScreen.tsx"
click node_signals "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/screens/SignalsScreen.tsx"
click node_watchlist "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/screens/WatchlistScreen.tsx"
click node_company "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/screens/CompanyDetailScreen.tsx"
click node_settings "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/screens/SettingsScreen.tsx"
click node_search "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/components/TickerSearchModal.tsx"
click node_feedhook "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/hooks/useInsiderFeed.ts"
click node_watchhook "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/hooks/useWatchlist.ts"
click node_companyhook "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/hooks/useCompany.ts"
click node_pricehook "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/hooks/useLivePrice.ts"
click node_api "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/lib/api.ts"
click node_cache "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/lib/queryClient.ts"
click node_supabaseclient "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/lib/supabase.ts"
click node_function "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/fetch-sec-filings/index.ts"
click node_request "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/fetch-sec-filings/request.ts"
click node_pipeline "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/ingest.ts"
click node_repository "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/repository.ts"
click node_edgar "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/edgar.ts"
click node_form4 "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/form4.ts"
click node_serverfinnhub "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/finnhub.ts"
click node_push "https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/push.ts"

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_auth,node_navigation,node_feed,node_signals,node_watchlist,node_company,node_settings,node_search,node_user toneBlue
class node_feedhook,node_watchhook,node_companyhook,node_pricehook,node_api,node_cache,node_supabaseclient toneAmber
class node_function,node_request,node_pipeline,node_repository,node_edgar,node_form4,node_serverfinnhub,node_push toneMint
class node_database,node_realtime toneRose
class node_scheduler,node_sec,node_finnhub toneIndigo
```

## Components

### InsiderPulse app

- [App bootstrap](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/App.tsx): `App.tsx`
- [Auth state](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/store/authStore.ts): `src/store/authStore.ts`
- [Navigation](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/navigation/RootNavigator.tsx): `src/navigation/RootNavigator.tsx`
- [Insider feed](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/screens/FeedScreen.tsx): `src/screens/FeedScreen.tsx`
- [WISI signals](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/screens/SignalsScreen.tsx): `src/screens/SignalsScreen.tsx`
- [Watchlist](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/screens/WatchlistScreen.tsx): `src/screens/WatchlistScreen.tsx`
- [Company detail](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/screens/CompanyDetailScreen.tsx): `src/screens/CompanyDetailScreen.tsx`
- [Settings](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/screens/SettingsScreen.tsx): `src/screens/SettingsScreen.tsx`
- [Ticker search](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/components/TickerSearchModal.tsx): `src/components/TickerSearchModal.tsx`

### Client data services

- [Feed subscription](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/hooks/useInsiderFeed.ts): `src/hooks/useInsiderFeed.ts`
- [Watchlist queries](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/hooks/useWatchlist.ts): `src/hooks/useWatchlist.ts`
- [Company queries](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/hooks/useCompany.ts): `src/hooks/useCompany.ts`
- [Live price hook](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/hooks/useLivePrice.ts): `src/hooks/useLivePrice.ts`
- [Data access API](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/lib/api.ts): `src/lib/api.ts`
- [Offline query cache](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/lib/queryClient.ts): `src/lib/queryClient.ts`
- [Supabase client](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/src/lib/supabase.ts): `src/lib/supabase.ts`

### Filing ingestion

- [Ingestion endpoint](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/fetch-sec-filings/index.ts): `supabase/functions/fetch-sec-filings/index.ts`
- [Request validation](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/fetch-sec-filings/request.ts): `supabase/functions/fetch-sec-filings/request.ts`
- [Ingest pipeline](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/ingest.ts): `supabase/functions/_shared/ingest.ts`
- [Ingest repository](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/repository.ts): `supabase/functions/_shared/repository.ts`
- [EDGAR client](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/edgar.ts): `supabase/functions/_shared/edgar.ts`
- [Form 4 parser](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/form4.ts): `supabase/functions/_shared/form4.ts`
- [Market-cap lookup](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/finnhub.ts): `supabase/functions/_shared/finnhub.ts`
- [Whale push alerts](https://github.com/ckeen302/senior_design_project/blob/claude/serene-wozniak-u9ca3f/supabase/functions/_shared/push.ts): `supabase/functions/_shared/push.ts`

### Supabase platform

- **Supabase data**
- **Supabase Realtime**

### Other components

- **App user**
- **pg_cron**
- **SEC EDGAR**
- **Finnhub services**

## Connections

- App user → App bootstrap: opens
- App bootstrap → Auth state: initializes (evidence: `App.tsx`)
- App bootstrap → Navigation: renders (evidence: `App.tsx`)
- Navigation → Insider feed: offers feed
- Navigation → WISI signals: offers signals
- Navigation → Watchlist: offers watchlist
- Navigation → Company detail: opens detail
- Navigation → Settings: offers settings
- Insider feed → Feed subscription: loads trades
- Feed subscription → Data access API: fetches feed (evidence: `src/hooks/useInsiderFeed.ts`)
- Feed subscription → Supabase Realtime: subscribes
- WISI signals → Data access API: loads scores
- Watchlist → Watchlist queries: loads list (evidence: `src/screens/WatchlistScreen.tsx`)
- Watchlist queries → Data access API: reads and updates (evidence: `src/hooks/useWatchlist.ts`)
- Company detail → Company queries: loads company (evidence: `src/screens/CompanyDetailScreen.tsx`)
- Company detail → Live price hook: loads price (evidence: `src/screens/CompanyDetailScreen.tsx`)
- Company queries → Data access API: fetches details (evidence: `src/hooks/useCompany.ts`)
- Live price hook → Finnhub services: gets live quotes (evidence: `src/hooks/useLivePrice.ts`)
- Ticker search → Data access API: searches and imports (evidence: `src/components/TickerSearchModal.tsx`)
- Ticker search → Watchlist queries: adds company (evidence: `src/components/TickerSearchModal.tsx`)
- Data access API → Supabase client: queries data (evidence: `src/lib/api.ts`)
- Supabase client → Supabase data: uses protected API (evidence: `src/lib/supabase.ts`)
- App bootstrap → Offline query cache: provides query cache (evidence: `App.tsx`)
- Offline query cache → Supabase data: persists cached results
- pg_cron → Ingestion endpoint: triggers ingestion
- Ingestion endpoint → Request validation: validates request (evidence: `supabase/functions/fetch-sec-filings/index.ts`)
- Ingestion endpoint → Ingest pipeline: runs pipeline (evidence: `supabase/functions/fetch-sec-filings/index.ts`)
- Ingestion endpoint → Ingest repository: creates repository (evidence: `supabase/functions/fetch-sec-filings/index.ts`)
- Ingestion endpoint → Whale push alerts: sends alerts (evidence: `supabase/functions/fetch-sec-filings/index.ts`)
- Ingest pipeline → EDGAR client: fetches filings (evidence: `supabase/functions/_shared/ingest.ts`)
- Ingest pipeline → Form 4 parser: parses filings (evidence: `supabase/functions/_shared/ingest.ts`)
- Ingest pipeline → Market-cap lookup: fetches market cap (evidence: `supabase/functions/_shared/ingest.ts`)
- Ingest pipeline → Ingest repository: reads and upserts (evidence: `supabase/functions/_shared/ingest.ts`)
- EDGAR client → SEC EDGAR: requests filings
- Market-cap lookup → Finnhub services: requests market cap
- Ingest repository → Supabase data: stores transactions
- Supabase data → Supabase Realtime: publishes changes
- Supabase data → Supabase data: recalculates WISI
- Supabase Realtime → Feed subscription: delivers live inserts
- Ingestion endpoint → Finnhub services: optional market data