Development Overview

AI Web Feeds is a mixed Python and TypeScript monorepo. The Python side powers the package, CLI, and optional backend. The TypeScript side powers the Next.js web app and docs.

Repository Layout

packages/ai_web_feeds/ contains the Python package
apps/cli/ contains the Typer-based CLI
apps/web/ contains the Next.js app and the docs site
tests/ contains the Python test suite
data/ contains the catalog, schemas, OPML exports, and local runtime files

Required Tooling

The repo enforces a split toolchain:

use uv run ... for Python commands
use pnpm ... for Node and web commands

Do not use bare python, pip, npm, or yarn in this repository.

Common Workflows

Run the web app

cd apps/web
pnpm install
pnpm dev

Run Python checks

uv run ruff check .
uv run pytest

Build the article library for the web app

uv run ai-web-feeds corpus refresh

Documentation Rules

User-facing documentation belongs in apps/web/content/docs/*.mdx. The docs site and the machine-readable llms.txt outputs are generated from that content.