# alpcakin/ai-financial-insights-system architecture

> Architecture diagram of the GitHub repository alpcakin/ai-financial-insights-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alpcakin/ai-financial-insights-system
- Repository: https://github.com/alpcakin/ai-financial-insights-system

## Overview

The product is a Flutter Android app backed by a FastAPI service for personalized financial news, AI analysis, portfolio-based alerts, and reports. The documented central workflow fetches and deduplicates news, analyzes articles with enabled providers, stores analyses, distributes matching articles using user holdings/topics and provider preferences, and generates impact alerts. The tree includes only the Android activity, not Flutter screens or repositories; those client details are therefore not mapped. Some backend services are represented at their exact file paths, but unsampled internals are not inferred.

Main entry points: [`backend/app/routers`](https://github.com/alpcakin/ai-financial-insights-system/tree/main/backend/app/routers) (API routes), [`backend/app/tasks/news_tasks.py`](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/tasks/news_tasks.py) (News cycle), [`backend/app/core/database.py`](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/core/database.py) (Supabase database), [`backend/app/services/alert_service.py`](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/alert_service.py) (Impact and volatility alerts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_mobile_app["Android app<br/>[MainActivity.kt]"]
end

subgraph group_api["API and accounts"]
  node_api_routes["API routes"]
  node_auth_service["Authentication<br/>[auth_service.py]"]
  node_security["JWT and password security<br/>[security.py]"]
  node_dependencies["Request authentication<br/>[dependencies.py]"]
  node_user_service["User profiles<br/>[user_service.py]"]
  node_database[("Supabase database<br/>[database.py]")]
  node_scheduler["In-process scheduler<br/>[main.py]"]
end

subgraph group_personalization["User personalization"]
  node_portfolio_service["Portfolio management"]
  node_watchlist_service["Watchlist management"]
  node_topic_service["Followed topics<br/>[topic_service.py]"]
  node_portfolio_model["Portfolio models<br/>[portfolio.py]"]
  node_watchlist_model["Watchlist models<br/>[watchlist.py]"]
  node_feed_service["Feed distribution and retrieval<br/>[feed_service.py]"]
end

subgraph group_news["News analysis"]
  node_news_jobs["News cycle<br/>[news_tasks.py]"]
  node_news_source["MediaStack news"]
  node_news_service["News fetching and deduplication<br/>[news_service.py]"]
  node_ai_analysis["Shared AI analysis<br/>[ai_service.py]"]
  node_provider_registry["Provider registry<br/>[registry.py]"]
  node_provider_interface["AI provider interface<br/>[base.py]"]
  node_provider_implementations["AI provider transports"]
end

subgraph group_alerts_reports["Alerts and reports"]
  node_alert_service["Impact and volatility alerts<br/>[alert_service.py]"]
  node_notification_service["Push notifications"]
  node_report_jobs["Weekly report job<br/>[report_tasks.py]"]
  node_report_service["Report generation<br/>[report_service.py]"]
end

node_user(("App user"))
node_fcm["Firebase Cloud Messaging"]
node_email["Resend email"]

node_user -->|"uses"| node_mobile_app
node_mobile_app -->|"calls API"| node_api_routes
node_api_routes -->|"delegates auth"| node_auth_service
node_auth_service -->|"reads and writes"| node_database
node_auth_service -->|"uses token tools"| node_security
node_auth_service -->|"sends verification"| node_email
node_api_routes -->|"requires auth"| node_dependencies
node_dependencies -->|"looks up user"| node_database
node_dependencies -->|"decodes JWT"| node_security
node_api_routes -->|"delegates profile"| node_user_service
node_api_routes -->|"delegates portfolio"| node_portfolio_service
node_api_routes -->|"delegates watchlist"| node_watchlist_service
node_api_routes -->|"delegates topics"| node_topic_service
node_portfolio_service -->|"uses categories"| node_topic_service
node_watchlist_service -->|"uses categories"| node_topic_service
node_scheduler -->|"schedules cycle"| node_news_jobs
node_scheduler -->|"schedules reports"| node_report_jobs
node_scheduler -->|"schedules volatility checks"| node_alert_service
node_news_jobs -->|"loads and stores data"| node_database
node_news_jobs -->|"fetches and deduplicates"| node_news_service
node_news_service -->|"fetches articles"| node_news_source
node_news_jobs -->|"gets enabled providers"| node_provider_registry
node_news_jobs -->|"analyzes articles"| node_ai_analysis
node_ai_analysis -->|"requests providers"| node_provider_registry
node_provider_registry -->|"registers implementations"| node_provider_interface
node_provider_implementations -->|"implements"| node_provider_interface
node_news_jobs -->|"distributes analyses"| node_feed_service
node_feed_service -->|"matches users and stores feed"| node_database
node_api_routes -->|"serves user feed"| node_feed_service
node_news_jobs -->|"creates impact alerts"| node_alert_service
node_alert_service -->|"stores alerts"| node_database
node_alert_service -->|"requests push"| node_notification_service
node_notification_service -->|"sends notifications"| node_fcm
node_api_routes -->|"serves alerts"| node_alert_service
node_report_jobs -->|"generates reports"| node_report_service
node_report_jobs -->|"uses database"| node_database
node_api_routes -->|"serves reports"| node_report_service

click node_mobile_app "https://github.com/alpcakin/ai-financial-insights-system/blob/main/mobile/android/app/src/main/kotlin/com/thesis/financial_insights/MainActivity.kt"
click node_api_routes "https://github.com/alpcakin/ai-financial-insights-system/tree/main/backend/app/routers"
click node_auth_service "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/auth_service.py"
click node_security "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/core/security.py"
click node_dependencies "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/dependencies.py"
click node_user_service "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/user_service.py"
click node_portfolio_service "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/portfolio_service.py"
click node_watchlist_service "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/watchlist_service.py"
click node_topic_service "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/topic_service.py"
click node_portfolio_model "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/models/portfolio.py"
click node_watchlist_model "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/models/watchlist.py"
click node_news_jobs "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/tasks/news_tasks.py"
click node_news_service "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/news_service.py"
click node_ai_analysis "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/ai_service.py"
click node_provider_registry "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/ai/registry.py"
click node_provider_interface "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/ai/base.py"
click node_provider_implementations "https://github.com/alpcakin/ai-financial-insights-system/tree/main/backend/app/services/ai"
click node_feed_service "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/feed_service.py"
click node_database "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/core/database.py"
click node_alert_service "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/alert_service.py"
click node_notification_service "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/notification_service.py"
click node_report_jobs "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/tasks/report_tasks.py"
click node_report_service "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/report_service.py"
click node_scheduler "https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/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_mobile_app,node_user toneBlue
class node_api_routes,node_auth_service,node_security,node_dependencies,node_user_service,node_database,node_scheduler toneAmber
class node_portfolio_service,node_watchlist_service,node_topic_service,node_portfolio_model,node_watchlist_model,node_feed_service toneMint
class node_news_jobs,node_news_source,node_news_service,node_ai_analysis,node_provider_registry,node_provider_interface,node_provider_implementations toneRose
class node_alert_service,node_notification_service,node_report_jobs,node_report_service,node_fcm,node_email toneIndigo
```

## Components

### Mobile client

- [Android app](https://github.com/alpcakin/ai-financial-insights-system/blob/main/mobile/android/app/src/main/kotlin/com/thesis/financial_insights/MainActivity.kt): `mobile/android/app/src/main/kotlin/com/thesis/financial_insights/MainActivity.kt`

### API and accounts

- [API routes](https://github.com/alpcakin/ai-financial-insights-system/tree/main/backend/app/routers): `backend/app/routers`
- [Authentication](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [JWT and password security](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Request authentication](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/dependencies.py): `backend/app/dependencies.py`
- [User profiles](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/user_service.py): `backend/app/services/user_service.py`
- [Supabase database](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [In-process scheduler](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/main.py): `backend/app/main.py`

### User personalization

- [Portfolio management](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/portfolio_service.py): `backend/app/services/portfolio_service.py`
- [Watchlist management](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/watchlist_service.py): `backend/app/services/watchlist_service.py`
- [Followed topics](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/topic_service.py): `backend/app/services/topic_service.py`
- [Portfolio models](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/models/portfolio.py): `backend/app/models/portfolio.py`
- [Watchlist models](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/models/watchlist.py): `backend/app/models/watchlist.py`
- [Feed distribution and retrieval](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/feed_service.py): `backend/app/services/feed_service.py`

### News analysis

- [News cycle](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/tasks/news_tasks.py): `backend/app/tasks/news_tasks.py`
- **MediaStack news**
- [News fetching and deduplication](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/news_service.py): `backend/app/services/news_service.py`
- [Shared AI analysis](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Provider registry](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/ai/registry.py): `backend/app/services/ai/registry.py`
- [AI provider interface](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/ai/base.py): `backend/app/services/ai/base.py`
- [AI provider transports](https://github.com/alpcakin/ai-financial-insights-system/tree/main/backend/app/services/ai): `backend/app/services/ai`

### Alerts and reports

- [Impact and volatility alerts](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/alert_service.py): `backend/app/services/alert_service.py`
- [Push notifications](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/notification_service.py): `backend/app/services/notification_service.py`
- [Weekly report job](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/tasks/report_tasks.py): `backend/app/tasks/report_tasks.py`
- [Report generation](https://github.com/alpcakin/ai-financial-insights-system/blob/main/backend/app/services/report_service.py): `backend/app/services/report_service.py`

### Other components

- **App user**
- **Firebase Cloud Messaging**
- **Resend email**

## Connections

- App user → Android app: uses (evidence: `README.md`)
- Android app → API routes: calls API (evidence: `README.md`)
- API routes → Authentication: delegates auth (evidence: `backend/app/routers/auth.py`)
- Authentication → Supabase database: reads and writes (evidence: `backend/app/services/auth_service.py`)
- Authentication → JWT and password security: uses token tools (evidence: `backend/app/services/auth_service.py`)
- Authentication → Resend email: sends verification (evidence: `backend/app/services/auth_service.py`)
- API routes → Request authentication: requires auth (evidence: `backend/app/routers/users.py`)
- Request authentication → Supabase database: looks up user (evidence: `backend/app/dependencies.py`)
- Request authentication → JWT and password security: decodes JWT (evidence: `backend/app/dependencies.py`)
- API routes → User profiles: delegates profile (evidence: `backend/app/routers/users.py`)
- API routes → Portfolio management: delegates portfolio (evidence: `backend/app/routers/portfolio.py`)
- API routes → Watchlist management: delegates watchlist (evidence: `backend/app/routers/watchlist.py`)
- API routes → Followed topics: delegates topics (evidence: `backend/app/routers/topics.py`)
- Portfolio management → Followed topics: uses categories (evidence: `backend/app/services/portfolio_service.py`)
- Watchlist management → Followed topics: uses categories (evidence: `backend/app/services/watchlist_service.py`)
- In-process scheduler → News cycle: schedules cycle (evidence: `backend/app/main.py`)
- In-process scheduler → Weekly report job: schedules reports (evidence: `backend/app/main.py`)
- In-process scheduler → Impact and volatility alerts: schedules volatility checks (evidence: `backend/app/main.py`)
- News cycle → Supabase database: loads and stores data (evidence: `backend/app/tasks/news_tasks.py`)
- News cycle → News fetching and deduplication: fetches and deduplicates (evidence: `backend/app/tasks/news_tasks.py`)
- News fetching and deduplication → MediaStack news: fetches articles
- News cycle → Provider registry: gets enabled providers (evidence: `backend/app/tasks/news_tasks.py`)
- News cycle → Shared AI analysis: analyzes articles (evidence: `backend/app/tasks/news_tasks.py`)
- Shared AI analysis → Provider registry: requests providers
- Provider registry → AI provider interface: registers implementations (evidence: `backend/app/services/ai/registry.py`)
- AI provider transports → AI provider interface: implements (evidence: `backend/app/services/ai/gemini.py`)
- News cycle → Feed distribution and retrieval: distributes analyses (evidence: `backend/app/tasks/news_tasks.py`)
- Feed distribution and retrieval → Supabase database: matches users and stores feed (evidence: `backend/app/services/feed_service.py`)
- API routes → Feed distribution and retrieval: serves user feed (evidence: `backend/app/routers/feed.py`)
- News cycle → Impact and volatility alerts: creates impact alerts (evidence: `backend/app/tasks/news_tasks.py`)
- Impact and volatility alerts → Supabase database: stores alerts (evidence: `backend/app/services/alert_service.py`)
- Impact and volatility alerts → Push notifications: requests push (evidence: `backend/app/services/alert_service.py`)
- Push notifications → Firebase Cloud Messaging: sends notifications (evidence: `README.md`)
- API routes → Impact and volatility alerts: serves alerts (evidence: `backend/app/routers/alerts.py`)
- Weekly report job → Report generation: generates reports (evidence: `backend/app/tasks/report_tasks.py`)
- Weekly report job → Supabase database: uses database (evidence: `backend/app/tasks/report_tasks.py`)
- API routes → Report generation: serves reports (evidence: `backend/app/routers/reports.py`)
