Auger/architecture.md

Architecture

Overview

Augor is a Flutter desktop application that aggregates business and finance news feeds, clusters related articles into events, uses an LLM to assess likely market impact, and outputs a probabilistic growth signal for each event.

MVP Goal

Deliver a working desktop prototype that:

• fetches articles from configured RSS/Atom feeds
• groups related reporting into event clusters
• asks an LLM to interpret each event cluster
• outputs a signal of growth, decline, or neutral
• includes a probability and confidence score
• displays results in the UI and exports them to JSON

What Is In Scope For MVP

• RSS/Atom feed ingestion
• Embedding generation for articles
• Relevance filtering for business/finance news
• Event clustering using cosine similarity
• LLM event interpretation per cluster
• Signal generation: growth, decline, neutral
• Probability/confidence scoring
• Result display in Flutter UI
• JSON export of generated signals

What Is Out Of Scope For MVP

• Backtesting
• Automated trading execution
• Backend/cloud processing
• Historical price-data integration
• Company/ticker extraction
• Multi-model comparison
• Advanced bias reduction or source weighting

Runtime Components

• lib/main.dart
  • App entrypoint.
  • Loads persisted settings before rendering UI.
  • Registers SettingsProvider in MultiProvider.
  • Configures navigation with go_router.
• lib/pages/home.dart
  • Main user flow trigger.
  • Runs feed fetch, embedding generation, relevance filtering, grouping, LLM signal generation, export, and result rendering.
• lib/pages/settings.dart
  • Settings UI for API key, feed list management, and output directory selection.
• lib/providers/settings.dart
  • ChangeNotifier state container.
  • Persists OpenRouter key, feed list, and storage path with SharedPreferences.
• lib/utils/agrigator.dart
  • Feed parsing, feed retrieval, embeddings, relevance filtering, and event grouping.
• lib/utils/openrouter.dart
  • OpenRouter API wrapper for embeddings and chat completions.
• lib/utils/signal_generator.dart
  • Builds event-cluster prompts.
  • Calls chat completions.
  • Parses structured JSON into app signal models.
• lib/models/event_signal.dart
  • Data model for a generated event signal.
• lib/widgets/event_signal_card.dart
  • Displays one generated signal in the UI.

MVP Data Flow

1. App startup loads persisted settings in SettingsProvider.load().
2. User starts analysis from the Home page.
3. App builds the list of enabled feed URLs.
4. Feeds are fetched and parsed into FeedItems.
5. Raw aggregated articles are exported to aggregated_feed.json.
6. Embeddings are generated for each article using text-embedding-3-small.
7. Enriched articles are exported to enriched_aggregated_feed.json.
8. Articles are filtered for business/finance relevance.
9. Relevant articles are exported to relevant_aggregated_feed.json.
10. Relevant articles are grouped into event clusters by cosine similarity.
11. Grouped readable output is exported.
12. Each event cluster is sent to an LLM prompt for interpretation.
13. The LLM returns structured JSON containing:
    • event_summary
    • signal
    • probability
    • confidence
    • rationale
14. Parsed signals are displayed in the UI.
15. Signals are exported to signals.json.

LLM Output Contract

Each analyzed event cluster must produce JSON in this shape:

{
  "event_summary": "short description of the event",
  "signal": "growth",
  "probability": 0.78,
  "confidence": 0.71,
  "rationale": "why this event suggests growth"
}

Allowed signal values:

• growth
• decline
• neutral

MVP Build Order

1. Add EventSignal model.
2. Add signal_generator.dart for prompt building and LLM parsing.
3. Wire signal generation into lib/pages/home.dart after clustering.
4. Add basic signal result rendering in the UI.
5. Export generated signals to signals.json.
6. Validate the end-to-end flow in the desktop app.

Current Constraints

• Processing is still UI-triggered and client-side only.
• No cancellation or progress reporting beyond basic UI state.
• No retry/backoff for network or model calls.
• No historical validation or backtesting in MVP.
• Quality of outputs depends on feed quality and LLM consistency.

Definition Of Done For MVP

• User clicks the main action on Home.
• App fetches articles from enabled feeds.
• App groups related stories into events.
• App generates one interpreted signal per event cluster.
• UI shows event summary, signal, probability, confidence, and rationale.
• Signals are written to signals.json in the configured output directory.