AI Daily Digest — Architecture & Build

📋 What it does

Every morning the app assembles a personal briefing and emails it as a single, clean HTML message. Each section comes from a dedicated module so sources can be added or swapped without touching the others:

Fetches news about South Africa and Amazon.
Gets weather for Mercer Island, WA and Cape Town, SA.
Pulls South African cricket scores and sports RSS feeds, plus Springboks rugby news.
Retrieves the top movies and TV shows.
Collects Oura ring health metrics — sleep, readiness, activity.
Formats everything into a mobile-friendly HTML email and sends it via Gmail SMTP.

        Same code, two homes: the exact same orchestrator runs locally with python main.py
        or as an AWS Lambda triggered by EventBridge on a daily schedule — with a lambda_handler() entry
        point and S3 holding state between runs.
      

🏗️ Architecture

main.py is the orchestrator: it calls each source module, normalises and validates the results, renders the email, and sends it. Modules are independent and fail soft, so one flaky API doesn't sink the whole digest.

flowchart TD
    EB[EventBridge
daily schedule] --> M
    M[main.py
orchestrator]
    M --> N[news.py
Serper API]
    M --> W[weather.py
NWS + Open-Meteo]
    M --> S[sports.py
CricAPI + RSS]
    M --> R[rugby.py
AI agent + web search]
    M --> MV[movies.py
Tavily API]
    M --> O[oura_pull.py
Oura API]
    O --> SC[smart_cache.py
S3-backed cache]
    N --> AI{{OpenAI
summarise + validate}}
    W --> AI
    S --> AI
    R --> AI
    MV --> AI
    O --> AI
    AI --> H[render HTML email]
    H --> G[Gmail SMTP send]
    classDef llm fill:#fef3c7,stroke:#d97706,color:#000
    class AI llm

Seven independent source modules fan in to the orchestrator; OpenAI cleans and validates before send.

🔌 Data sources

Each module owns one source and one API, returning ready-to-render content to the orchestrator.

Module	Source / API	Provides
news.py	Serper (Google search)	South Africa & Amazon news
weather.py	NWS + Open-Meteo	US & international forecasts
sports.py	CricAPI + RSS	SA cricket scores + sports feeds
rugby.py	AI agent + web search	Springboks rugby news
movies.py	Tavily search	Top movies & TV shows
oura_pull.py	Oura API	Sleep, readiness & activity
smart_cache.py	S3 / local JSON	Caches Oura analysis to cut API cost

☁️ Stack & components

🐍 Python orchestrator

main.py coordinates fetching, sanitising, formatting, validation, and sending — with token accounting on every OpenAI call.

⚡ AWS Lambda

A lambda_handler() entry point runs the same code in the cloud; Docker-built deploy packages ship it.

⏰ EventBridge

A scheduled rule fires the Lambda once a day so the digest arrives without any manual trigger.

🤖 OpenAI

Summarises noisy source content into clean bullets and optionally validates the final email's formatting.

🪣 Amazon S3

Holds state between Lambda runs — cached Oura metrics, analysis, and API usage counters.

💍 Oura + smart cache

Pulls 90 days of health data, "heals" gaps caused by Oura API quirks, and caches AI analysis to reduce cost.

✉️ Gmail SMTP

Assembles a MIME multipart message and delivers the mobile-friendly HTML email to the inbox.

📐 Structured output

JSON schemas constrain the LLM's news output so rendering stays predictable and safe to template.

🔄 End-to-end run

Schedule fires

EventBridge triggers the Lambda (or a local cron / manual run) once a day to start the digest build.

Fan out to sources

The orchestrator calls each source module — news, weather, sports, rugby, movies, Oura — independently, so a single failing API degrades gracefully instead of breaking the run.

Summarise & sanitise

OpenAI condenses noisy content into clean bullets against JSON schemas; URL and text sanitisers strip tracking params and de-dupe, all under per-run token accounting.

Heal & cache health data

Oura history is back-filled around the API's single-day quirk and cached in S3 so repeat analysis doesn't re-spend tokens.

Render the email

All sections are assembled into a mobile-friendly HTML template and packed into a MIME multipart message — with an optional AI pass that validates the formatting.

Send

The digest goes out via Gmail SMTP and lands in the inbox — one concise briefing instead of a morning of scattered reading.

💡 What it demonstrates

Clean modular design — one module per source, each with a single responsibility, so the system is easy to extend and resilient to any one API failing.
Practical LLM use — the model is a summariser and validator constrained by JSON schemas, not a black box; output stays predictable and templatable.
Cost-aware engineering — token accounting on every call plus an S3-backed cache that avoids re-spending on unchanged data.
Run-anywhere deployment — the same code runs locally or as a scheduled serverless function, with state externalised to S3.