AINewsTracker

1. Overview

app/main.py assembles the service, registers the route groups and configures Redis caching. News processing moves through a service, text metrics and the article repository before reaching MongoDB.

The companion article, Following financial news through AINewsTracker, follows that path from an incoming feed to a stored article.

3. Getting started

cp .env.example .env
pip install poetry
poetry shell
poetry install
poetry run pytest
poetry run uvicorn app.main:app --reload

FastAPI documentation is available at http://localhost:8000/api/v1/docs according to the project guide. Docker users can start the documented stack with:

docker-compose up --build

4. Repository guide

• app/main.py creates the application, registers routers and configures caching.
• app/routers/ defines news, article, company, user, seed and strategy endpoints.
• app/core/services/ contains news processing and text metrics.
• app/core/repo/ contains persistence operations grouped by domain.
• app/models/ defines records accepted and returned by the service.
• app/seed/ loads company and news data from external sources.
• app/core/trading/strategy.py handles strategy requests.

5. Features

• ingest news through RSS, GNews and configured feeds;
• analyse sentiment, topics and ticker allocation;
• manage article, company, news and user records;
• seed company and news data;
• execute strategy requests for one or more companies;
• run through Poetry or Docker Compose.

6. Architecture

This view condenses the runtime boundaries verified by GitDiagram. The full interactive diagram expands the model and links components to their source.

flowchart TD
  Client(("API client")) --> App["FastAPI application<br/>app/main.py"]
  App --> Routes["Routers<br/>app/routers/"]
  Routes --> News["News processing<br/>app/core/services/news.py"]
  News --> Metrics["Text metrics<br/>app/core/services/metrics.py"]
  News --> Repos["Repositories<br/>app/core/repo/"]
  Routes --> Repos
  Repos --> Mongo[("MongoDB<br/>app/core/database/db.py")]
  App --> Redis[("Redis cache<br/>app/core/database/db.py")]
  Sources{{"Financial news sources"}} --> Seeders["Seeders<br/>app/seed/"]
  Seeders --> News
  Routes --> Strategy["Trading strategy<br/>app/core/trading/strategy.py"]

7. API contract

The running FastAPI OpenAPI document is the authority for exact request and response schemas.

8. Deployment

The repository includes a root Dockerfile, a development docker-compose.yml and a separate deploy/ directory. Compose dependency ordering is a startup order, not a readiness guarantee.

9. Code structure

app/
├── main.py
├── core/{database,repo,services,telemetry,trading}/
├── models/
├── routers/
└── seed/
tests/
deploy/
monitoring/

10. Limits

• Sentiment and topic labels are analytical inputs, not financial advice or proof of causation.
• Historical backtests do not guarantee future performance.
• External feeds and market APIs have their own credentials, availability and usage terms.
• Endpoint details can change; current source and OpenAPI take precedence.

11. Sources

• GitHub repository
• Project documentation
• GitDiagram architecture
• app/main.py
• app/routers/news.py
• app/core/services/news.py
• app/core/services/metrics.py

flowchart LR
  subgraph wf0["Python application CD"]
    direction LR
    wf0_setup[["setup<br/>ubuntu-latest"]]
  end
  subgraph wf1["Python application CI"]
    direction LR
    wf1_setup["setup<br/>ubuntu-latest"]
  end
  subgraph wf2["CodeQL"]
    direction LR
    wf2_analyze["Analyze<br/>ubuntu-latest"]
  end
  subgraph wf3["Docker CI"]
    direction LR
    wf3_docker[["docker<br/>ubuntu-latest"]]
  end
  subgraph wf4["AINewsTracker Docs"]
    direction LR
    wf4_build_and_deploy[["build_and_deploy<br/>ubuntu-latest"]]
  end
  t0(["release"])
  t1(["pull request · push"])
  t2(["push · pull request · schedule"])
  t3(["push"])
  t4(["push · pull request · manual run"])
  d0[("Container registry")]
  d1[("GitHub Pages")]
  t0 --> wf0_setup
  wf0_setup -.-> d0
  t1 --> wf1_setup
  t2 --> wf2_analyze
  t3 --> wf3_docker
  wf3_docker -.-> d0
  t4 --> wf4_build_and_deploy
  wf4_build_and_deploy -.-> d1

flowchart LR
  repo[("GitHub repository")]
  ci[["GitHub Actions<br/>5 workflows"]]
  image["Docker image<br/>FROM tiangolo/uvicorn-gunicorn-fastapi:python3.10"]
  pub_Container_registry[("Container registry")]
  pub_GitHub_Pages[("GitHub Pages")]
  host_Vercel("Vercel<br/>vercel.json")
  host_MkDocs_site("Documentation site (MkDocs)<br/>mkdocs.yml")
  subgraph compose["Docker Compose"]
    svc_redis["redis"]
    svc_mongo["mongo"]
    svc_web["web"]
    svc_prometheus["prometheus"]
  end
  repo -->|"push or pull request"| ci
  ci -->|"docker build"| image
  image -->|"publishes"| pub_Container_registry
  ci -->|"publishes"| pub_GitHub_Pages
  ci -.->|"configured"| host_Vercel
  ci -.->|"configured"| host_MkDocs_site
  image -->|"docker compose up"| compose