# 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 `FeedItem`s.
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:

```json
{
  "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.