An automated weekly newsletter about coffee (PT-BR). It collects news from global RSS feeds, summarizes them with the Claude API, and delivers them by email.
Status: 🟢 In production · Weekly automation via GitHub Actions
🌐 Live: coado.club
A fullstack project combining:
- Signup site + API — a static frontend (Vercel) talking to a FastAPI service (AWS Lambda) that manages subscriptions and exposes public stats.
- Automation pipeline — RSS scraper → Claude API → Resend email delivery, running weekly on GitHub Actions.
It is deliberately built as something simple (a coffee newsletter) on top of a robust, modular architecture — the stack is where the learning happens.
A modular monolith in a monorepo: apps/ holds thin entrypoints, packages/
holds all reusable domain and infrastructure logic.
coffee-newsletter/
├── apps/
│ ├── api/ ← FastAPI app (routes, schemas, dependencies)
│ ├── web/ ← Static frontend (hosted on Vercel)
│ └── newsletter_pipeline/ ← Weekly pipeline entrypoint
├── packages/
│ ├── ai/ ← Claude API integration
│ ├── core/ ← Shared config (Pydantic Settings)
│ ├── database/ ← SQLAlchemy base, sessions, models, repositories, Alembic migrations
│ ├── mailer/ ← Mail provider abstractions (Resend, ...)
│ ├── newsletter/ ← Newsletter domain logic, templates, prompts
│ └── scraper/ ← RSS collection and scraping
├── pyproject.toml ← Dependencies (uv)
├── Makefile · compose.yaml · template.yaml · alembic.ini
📚 Full documentation lives in docs/:
- Architecture overview
- Architecture decisions — why AWS Lambda, why no agent frameworks, why a cron over a worker
- Packages
- Getting started
- Environment variables
- Deployment
- Pipeline
git clone git@github.com:CardosoGuiVi/coffee-newsletter.git
cd coffee-newsletter
uv sync
cp .env.example .env # then edit with your credentials
make fastapi-dev # API at http://localhost:8000 (routes under /v1/)To run the static frontend locally:
cd apps/web && python3 -m http.server 8080See getting started for pointing the frontend at the local API.
| Area | Tools |
|---|---|
| Language | Python 3.12, uv |
| Backend | FastAPI, SQLAlchemy 2.0 async, asyncpg, Alembic, Pydantic v2 |
| Resend, Jinja2 templates | |
| AI | Anthropic Claude API (claude-haiku-4-5) |
| Frontend | Vanilla HTML/CSS/JS |
| Infra | AWS Lambda (API, SAM), Neon (PostgreSQL), Vercel, GitHub Actions |
| Local dev | Docker Compose (PostgreSQL), Makefile |
| Quality | ruff, mypy, pre-commit, Dependabot |
| Component | Platform | Trigger |
|---|---|---|
| API | AWS Lambda (sa-east-1) | SAM — make deploy |
| Frontend | Vercel | main → production, others → preview |
| Pipeline | AWS Lambda (sa-east-1) | EventBridge Scheduler — Mondays 11:00 UTC (08:00 BRT) |
The frontend reaches the API through a Vercel rewrite proxy (/v1/* → Lambda Function URL),
so the browser stays on one origin and there is no CORS to manage. Details in
deployment.
See ROADMAP.md for the current short-, medium-, and long-term
plan. In short: tests and security hardening next, applied-AI topics (embeddings,
RAG, vector DBs) further out.
MIT — see LICENSE.
Maintained by: Guilherme Cardoso