AI News Commentator

An AI-driven platform that curates news from RSS feeds and APIs, provides AI-powered elaborations with strict attribution, enables personal commentary capture through Q&A, and generates publishable drafts for LinkedIn and Substack with automated roundup scheduling.

Project Architecture

**Principles**: Serverless-first, AWS-native, TypeScript end-to-end, strict attribution handling

**Tech Stack**:

Development Workflow

Setup Commands

```bash

npm install # Install dependencies

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

npm run build # Build project

npm run test # Run tests

npm run test:watch # Run tests in watch mode

npm run lint # Lint code

npm run type-check # TypeScript validation

npm run db:migrate # Run database migrations

npm run db:seed # Seed database

npm run clean # Clean builds

```

Project Structure

Development Process

**CRITICAL: Follow this mandatory process for EVERY development task:**

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

2. **Validate Code** (ALWAYS run ALL steps before committing):

```bash

npm run build # Ensure code compiles

npm run lint # Check code style

npm run type-check # Verify TypeScript

npm run test # Run all tests

```

**Fix any errors before proceeding - NEVER commit failing code**

3. **Review Changes**:

```bash

git status # See modified files

git diff # Review modifications

```

4. **Stage Files**:

```bash

git add <files> # Stage only relevant files

```

5. **Commit Changes**:

```bash

git commit -m "<type>: <description>"

```

- Use branch name to derive issue number if applicable

- Keep messages concise and professional

- Example: `test: add basic test files and fix missing dependencies`

**Commit Message Types**:

Git Rules

**CRITICAL RULES**:

**When to Commit**:

PR Creation Process

1. Review all changes: `git diff main...HEAD`

2. Run full test suite: `npm run test`

3. Create PR with descriptive title and body

4. Include "Test plan" section with validation steps

5. Tag reviewers if needed

Coding Guidelines

Data Model

**DynamoDB Tables**:

**OpenSearch Index**: `items_idx` for ranking and search

LLM Integration

**Provider Strategy**:

**Key Prompts**:

MVP Features (Milestone 1)

Acceptance Criteria

Implementation Notes

External Dependencies