How alpcakin/ai-financial-insights-system works
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: routers API routes · news_tasks.py News cycle · database.py Supabase database · alert_service.py Impact and volatility alerts
Components 28
Mobile client
- Android app
mobile/android/app/src/main/kotlin/com/thesis/financial_insights/MainActivity.kt
API and accounts
- API routes
backend/app/routers - Authentication
backend/app/services/auth_service.py - JWT and password security
backend/app/core/security.py - Request authentication
backend/app/dependencies.py - User profiles
backend/app/services/user_service.py - Supabase database
backend/app/core/database.py - In-process scheduler
backend/app/main.py
User personalization
- Portfolio management
backend/app/services/portfolio_service.py - Watchlist management
backend/app/services/watchlist_service.py - Followed topics
backend/app/services/topic_service.py - Portfolio models
backend/app/models/portfolio.py - Watchlist models
backend/app/models/watchlist.py - Feed distribution and retrieval
backend/app/services/feed_service.py
News analysis
- News cycle
backend/app/tasks/news_tasks.py - MediaStack news
- News fetching and deduplication
backend/app/services/news_service.py - Shared AI analysis
backend/app/services/ai_service.py - Provider registry
backend/app/services/ai/registry.py - AI provider interface
backend/app/services/ai/base.py - AI provider transports
backend/app/services/ai
Alerts and reports
- Impact and volatility alerts
backend/app/services/alert_service.py - Push notifications
backend/app/services/notification_service.py - Weekly report job
backend/app/tasks/report_tasks.py - Report generation
backend/app/services/report_service.py
Other components
- App user
- Firebase Cloud Messaging
- Resend email
Connections 37
- App user → Android app: uses
README.md - Android app → API routes: calls API
README.md - API routes → Authentication: delegates auth
backend/app/routers/auth.py - Authentication → Supabase database: reads and writes
backend/app/services/auth_service.py - Authentication → JWT and password security: uses token tools
backend/app/services/auth_service.py - Authentication → Resend email: sends verification
backend/app/services/auth_service.py - API routes → Request authentication: requires auth
backend/app/routers/users.py - Request authentication → Supabase database: looks up user
backend/app/dependencies.py - Request authentication → JWT and password security: decodes JWT
backend/app/dependencies.py - API routes → User profiles: delegates profile
backend/app/routers/users.py - API routes → Portfolio management: delegates portfolio
backend/app/routers/portfolio.py - API routes → Watchlist management: delegates watchlist
backend/app/routers/watchlist.py - API routes → Followed topics: delegates topics
backend/app/routers/topics.py - Portfolio management → Followed topics: uses categories
backend/app/services/portfolio_service.py - Watchlist management → Followed topics: uses categories
backend/app/services/watchlist_service.py - In-process scheduler → News cycle: schedules cycle
backend/app/main.py - In-process scheduler → Weekly report job: schedules reports
backend/app/main.py - In-process scheduler → Impact and volatility alerts: schedules volatility checks
backend/app/main.py - News cycle → Supabase database: loads and stores data
backend/app/tasks/news_tasks.py - News cycle → News fetching and deduplication: fetches and deduplicates
backend/app/tasks/news_tasks.py - News fetching and deduplication → MediaStack news: fetches articles
- News cycle → Provider registry: gets enabled providers
backend/app/tasks/news_tasks.py - News cycle → Shared AI analysis: analyzes articles
backend/app/tasks/news_tasks.py - Shared AI analysis → Provider registry: requests providers
- Provider registry → AI provider interface: registers implementations
backend/app/services/ai/registry.py - AI provider transports → AI provider interface: implements
backend/app/services/ai/gemini.py - News cycle → Feed distribution and retrieval: distributes analyses
backend/app/tasks/news_tasks.py - Feed distribution and retrieval → Supabase database: matches users and stores feed
backend/app/services/feed_service.py - API routes → Feed distribution and retrieval: serves user feed
backend/app/routers/feed.py - News cycle → Impact and volatility alerts: creates impact alerts
backend/app/tasks/news_tasks.py - Impact and volatility alerts → Supabase database: stores alerts
backend/app/services/alert_service.py - Impact and volatility alerts → Push notifications: requests push
backend/app/services/alert_service.py - Push notifications → Firebase Cloud Messaging: sends notifications
README.md - API routes → Impact and volatility alerts: serves alerts
backend/app/routers/alerts.py - Weekly report job → Report generation: generates reports
backend/app/tasks/report_tasks.py - Weekly report job → Supabase database: uses database
backend/app/tasks/report_tasks.py - API routes → Report generation: serves reports
backend/app/routers/reports.py