# hahaarthur17/ai-bull-vs-bear architecture

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

- Interactive diagram: https://gitdiagram.com/hahaarthur17/ai-bull-vs-bear
- Repository: https://github.com/hahaarthur17/ai-bull-vs-bear

## Overview

AI Bull vs Bear is an educational stock-research app: users select a stock, inspect prices, technical indicators and evidence, then review a cited Bull/Bear analysis, uncertainty and claim examinations. The mobile app calls a FastAPI backend; the backend combines market context, evidence retrieval and analysis, with demo fallbacks and optional authenticated persistence and model providers. RSS, SEC and market-data ingestion support the evidence and price views. The graph reflects documented capabilities; several backend orchestration details are based on the README because their implementations were not sampled.

Main entry points: [`backend/app/main.py`](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/main.py) (HTTP routes), [`backend/app/services/analysis.py`](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/analysis.py) (Analysis orchestration), [`backend/app/services/supabase_store.py`](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/supabase_store.py) (Supabase persistence), [`apps/mobile/App.tsx`](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/apps/mobile/App.tsx) (Research screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_mobile_app["Research screens<br/>[App.tsx]"]
  node_mobile_auth["Sign-in<br/>[AuthScreen.tsx]"]
  node_mobile_api["API client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_fastapi["HTTP routes<br/>[main.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_auth["Token verification<br/>[auth.py]"]
end

subgraph group_analysis["Analysis workflow"]
  node_analysis_service["Analysis orchestration<br/>[analysis.py]"]
  node_indicators["Technical indicators<br/>[indicators.py]"]
  node_rag["Evidence retrieval<br/>[rag.py]"]
  node_freshness["Evidence freshness"]
  node_guardrails["Safety guardrails<br/>[guardrails.py]"]
  node_model_provider["Model providers<br/>[model_provider.py]"]
end

subgraph group_data["Data and integrations"]
  node_demo_store[("Demo data<br/>[demo_store.py]")]
  node_supabase_store[("Supabase persistence<br/>[supabase_store.py]")]
  node_evidence_ingestion["SEC ingestion"]
  node_rss_ingestion["RSS ingestion<br/>[ingestion.py]"]
  node_market_data["Market data<br/>[market_data.py]"]
  node_macro_data["Macro context<br/>[macro_data.py]"]
  node_supabase_db[("Supabase database<br/>[schema.sql]")]
end

node_researcher(("Researcher"))
node_model_apis["Groq / Gemini"]
node_market_sources["Market providers"]
node_rss_sec["RSS / SEC EDGAR"]
node_ingestion_run(("Ingestion trigger"))
node_supabase_auth["Supabase Auth"]

node_researcher -->|"uses"| node_mobile_app
node_mobile_app -->|"opens"| node_mobile_auth
node_mobile_app -->|"requests data"| node_mobile_api
node_mobile_api -->|"calls API"| node_fastapi
node_fastapi -->|"validates"| node_schemas
node_fastapi -->|"verifies token"| node_auth
node_auth -.->|"validates session"| node_supabase_auth
node_fastapi -->|"delegates analysis"| node_analysis_service
node_fastapi -->|"calculates signals"| node_indicators
node_fastapi -->|"searches evidence"| node_rag
node_analysis_service -->|"gets signals"| node_indicators
node_analysis_service -->|"retrieves evidence"| node_rag
node_analysis_service -->|"checks evidence"| node_freshness
node_analysis_service -->|"requests debate"| node_model_provider
node_analysis_service -->|"checks claims"| node_guardrails
node_analysis_service -.->|"persists analysis"| node_supabase_store
node_analysis_service -->|"uses demo data"| node_demo_store
node_model_provider -.->|"calls provider"| node_model_apis
node_fastapi -->|"reads demo data"| node_demo_store
node_fastapi -.->|"reads or writes"| node_supabase_store
node_supabase_store -.->|"reads or writes"| node_supabase_db
node_demo_store -->|"provides evidence"| node_rag
node_ingestion_run -->|"starts import"| node_rss_ingestion
node_ingestion_run -->|"starts import"| node_evidence_ingestion
node_ingestion_run -->|"starts import"| node_market_data
node_rss_ingestion -->|"fetches feeds"| node_rss_sec
node_evidence_ingestion -->|"fetches filings"| node_rss_sec
node_rss_ingestion -->|"stores evidence"| node_supabase_store
node_evidence_ingestion -->|"stores evidence"| node_supabase_store
node_market_data -.->|"fetches prices"| node_market_sources
node_market_data -.->|"stores prices"| node_supabase_store
node_macro_data -.->|"reads context"| node_supabase_store
node_fastapi -->|"loads macro context"| node_macro_data

click node_mobile_app "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/apps/mobile/App.tsx"
click node_mobile_auth "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/apps/mobile/src/AuthScreen.tsx"
click node_mobile_api "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/apps/mobile/src/api.ts"
click node_fastapi "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/main.py"
click node_schemas "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/schemas.py"
click node_auth "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/auth.py"
click node_analysis_service "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/analysis.py"
click node_indicators "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/indicators.py"
click node_rag "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/rag.py"
click node_freshness "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/evidence_freshness.py"
click node_guardrails "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/guardrails.py"
click node_model_provider "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/model_provider.py"
click node_demo_store "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/demo_store.py"
click node_supabase_store "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/supabase_store.py"
click node_evidence_ingestion "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/evidence_ingestion.py"
click node_rss_ingestion "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/ingestion.py"
click node_market_data "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/market_data.py"
click node_macro_data "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/macro_data.py"
click node_supabase_db "https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/supabase/schema.sql"

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_mobile_app,node_mobile_auth,node_mobile_api toneBlue
class node_fastapi,node_schemas,node_auth toneAmber
class node_analysis_service,node_indicators,node_rag,node_freshness,node_guardrails,node_model_provider toneMint
class node_demo_store,node_supabase_store,node_evidence_ingestion,node_rss_ingestion,node_market_data,node_macro_data,node_supabase_db toneRose
class node_researcher,node_model_apis,node_market_sources,node_rss_sec,node_ingestion_run,node_supabase_auth toneIndigo
```

## Components

### Mobile app

- [Research screens](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/apps/mobile/App.tsx): `apps/mobile/App.tsx`
- [Sign-in](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/apps/mobile/src/AuthScreen.tsx): `apps/mobile/src/AuthScreen.tsx`
- [API client](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/apps/mobile/src/api.ts): `apps/mobile/src/api.ts`

### Backend API

- [HTTP routes](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/main.py): `backend/app/main.py`
- [API schemas](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Token verification](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/auth.py): `backend/app/services/auth.py`

### Analysis workflow

- [Analysis orchestration](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/analysis.py): `backend/app/services/analysis.py`
- [Technical indicators](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/indicators.py): `backend/app/services/indicators.py`
- [Evidence retrieval](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/rag.py): `backend/app/services/rag.py`
- [Evidence freshness](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/evidence_freshness.py): `backend/app/services/evidence_freshness.py`
- [Safety guardrails](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/guardrails.py): `backend/app/services/guardrails.py`
- [Model providers](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/model_provider.py): `backend/app/services/model_provider.py`

### Data and integrations

- [Demo data](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/demo_store.py): `backend/app/services/demo_store.py`
- [Supabase persistence](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/supabase_store.py): `backend/app/services/supabase_store.py`
- [SEC ingestion](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/evidence_ingestion.py): `backend/app/services/evidence_ingestion.py`
- [RSS ingestion](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/ingestion.py): `backend/app/services/ingestion.py`
- [Market data](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/market_data.py): `backend/app/services/market_data.py`
- [Macro context](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/app/services/macro_data.py): `backend/app/services/macro_data.py`
- [Supabase database](https://github.com/hahaarthur17/ai-bull-vs-bear/blob/main/backend/supabase/schema.sql): `backend/supabase/schema.sql`

### Other components

- **Researcher**
- **Groq / Gemini**
- **Market providers**
- **RSS / SEC EDGAR**
- **Ingestion trigger**
- **Supabase Auth**

## Connections

- Researcher → Research screens: uses
- Research screens → Sign-in: opens
- Research screens → API client: requests data
- API client → HTTP routes: calls API
- HTTP routes → API schemas: validates
- HTTP routes → Token verification: verifies token
- Token verification → Supabase Auth: validates session
- HTTP routes → Analysis orchestration: delegates analysis
- HTTP routes → Technical indicators: calculates signals
- HTTP routes → Evidence retrieval: searches evidence
- Analysis orchestration → Technical indicators: gets signals
- Analysis orchestration → Evidence retrieval: retrieves evidence
- Analysis orchestration → Evidence freshness: checks evidence
- Analysis orchestration → Model providers: requests debate
- Analysis orchestration → Safety guardrails: checks claims
- Analysis orchestration → Supabase persistence: persists analysis
- Analysis orchestration → Demo data: uses demo data
- Model providers → Groq / Gemini: calls provider
- HTTP routes → Demo data: reads demo data
- HTTP routes → Supabase persistence: reads or writes
- Supabase persistence → Supabase database: reads or writes
- Demo data → Evidence retrieval: provides evidence
- Ingestion trigger → RSS ingestion: starts import
- Ingestion trigger → SEC ingestion: starts import
- Ingestion trigger → Market data: starts import
- RSS ingestion → RSS / SEC EDGAR: fetches feeds
- SEC ingestion → RSS / SEC EDGAR: fetches filings
- RSS ingestion → Supabase persistence: stores evidence
- SEC ingestion → Supabase persistence: stores evidence
- Market data → Market providers: fetches prices
- Market data → Supabase persistence: stores prices
- Macro context → Supabase persistence: reads context
- HTTP routes → Macro context: loads macro context