AI News Aggregator System

You are working on an AI-driven news curation and commentary platform that aggregates content from RSS feeds and APIs, provides AI-powered elaborations with strict citation requirements, captures personal commentary through Q&A prompts, and generates publishable drafts for LinkedIn and Substack.

Project Architecture

**Stack Overview:**

**Project Structure:**

```

/backend - Lambda functions and API server

/frontend - Remix/Next.js web application

/shared - Shared TypeScript types and utilities

/docs - Documentation and PRD

/tests - Test files (Vitest)

/database - Migrations and seeds

```

Development Workflow

MANDATORY Pre-Commit Validation

Before EVERY commit, you MUST run all validation steps:

1. **Build**: `npm run build` - Verify compilation succeeds

2. **Lint**: `npm run lint` - Check code style

3. **Type Check**: `npm run type-check` - Verify TypeScript types

4. **Tests**: `npm run test` - Run full test suite

**NEVER commit failing code.** Fix all errors before proceeding.

Standard Development Process

1. **Make Changes**: Implement features, write tests, update documentation

2. **Validate Code**: Run ALL validation commands listed above

3. **Review Changes**:

- `git status` - See modified files

- `git diff` - Review line-by-line changes

4. **Stage Files**: `git add <files>` - Stage only relevant changes

5. **Commit Changes**: Use clean, professional commit messages

Commit Message Format

```

<type>: <description>

Types: feat, fix, test, chore, refactor, docs

Example: test: add elaboration citation validation tests

```

**CRITICAL RULES:**

Branch Naming Convention

```

type/personid-linearid-description

Example: feature/macs-MAC-121-ticket-prd

```

Core Development Commands

```bash

Development

npm install # Install dependencies

npm run dev # Start dev server (backend:3001, frontend:3000)

npm run build # Build project

npm run clean # Clean build artifacts

Quality Assurance

npm run test # Run tests

npm run test:watch # Run tests in watch mode

npm run lint # Lint code

npm run type-check # TypeScript type checking

Database

npm run db:migrate # Run migrations

npm run db:seed # Seed database

```

Key Features & Implementation

1. News Curation Pipeline

**Data Sources:**

**Feed Card Requirements:**

2. AI Elaboration System

**Elaboration Requirements:**

**LLM Strategy:**

**Performance Targets:**

3. Commentary Capture (Q&A System)

Generate 3-5 POV prompts per article:

**Requirements:**

4. Draft Generation

**Platform-Specific Templates:**

**Draft Features:**

5. Publishing Flow

**OAuth Integration:**

**Success Criteria:**

6. Automated Roundups

**Scheduler:**

**Roundup Generation:**

Data Model (DynamoDB)

Core Tables

**Users**: User profiles, preferences, topics, keywords, regions, sources

**Sources**: RSS feeds and API sources with trust scores

**Items**: Normalized articles with dedupe clustering

**UserItemState**: User actions (viewed, saved, dismissed, interesting)

**Elaborations**: AI summaries with citations and takeaways

**QnAResponses**: User commentary per item

**Drafts**: Generated content with version history

**Roundups**: Scheduled content compilations

**Tokens**: Encrypted OAuth credentials

OpenSearch Index

`items_idx` - For ranking, search, and relevance scoring

Quality Standards

Acceptance Criteria

Code Quality

UX Guidelines

External Dependencies & Configuration

**Required API Keys:**

**AWS Services:**

Implementation Reference

Follow the detailed implementation plan in `docs/milestone-1-implementation-plan.md` for step-by-step guidance on building each feature.

Important Constraints

1. **Serverless-first**: All backend logic must run on AWS Lambda

2. **Strict attribution**: Every AI elaboration MUST include verified citations

3. **TypeScript end-to-end**: No JavaScript files except config

4. **Test coverage**: All features require Vitest tests before merge

5. **Security**: OAuth tokens encrypted, KMS for sensitive data, no hardcoded credentials