PatchNotes

A GitHub release viewer for npm packages. Track release notes across your favorite packages in one place.

Forged in Gas Town

Deployment

Environment	URL	Status
Frontend	https://app.mypkgupdate.com	Live
API	https://api-mypkgupdate-com.azurewebsites.net	Live

Project Status

Stage: Development (MVP) Health Score: 8/10

Area	Status
Architecture	✅ Solid (.NET + React separation)
Code Quality	✅ Good
CI/CD	✅ GitHub Actions (build, test, deploy)
Testing	✅ 141 Vitest tests + xUnit API/Sync tests
Authentication	✅ Stytch B2C configured
Error Handling	✅ Error boundaries + toast notifications

Features

• Package Tracking - Add npm packages to monitor their GitHub releases
• Release Timeline - Mobile-first timeline view grouped by date
• Package Picker - Filter releases by selected packages
• Sync Engine - Fetch releases from GitHub with rate limit awareness
• AI Summaries - Generate concise release note summaries using Groq LLM
• Design System - Consistent visual language across components

Architecture

• PatchNotes.Data - EF Core models, SQLite database, GitHub API client, Groq LLM client
• PatchNotes.Api - ASP.NET Core Web API (port 5031)
• PatchNotes.Sync - Console app to fetch releases from GitHub
• patchnotes-web - React frontend with TanStack Router & Query

Prerequisites

• .NET 10 SDK
• Node.js 18+
• direnv (recommended for secrets management)

Configuration

The project uses direnv for environment-based configuration. Create a secrets file at ~/.secrets/patchnotes/.env.local:

# Required for API authentication
APIKEY=your-api-key

# Required for GitHub API (increases rate limit)
GITHUB__TOKEN=your-github-token

# Required for AI summaries
GROQ__APIKEY=your-groq-api-key

# Optional: customize the LLM model (default: llama-3.3-70b-versatile)
# GROQ__MODEL=llama-3.3-70b-versatile

Get a Groq API key at https://console.groq.com/keys

Authentication

The app uses Stytch for B2C authentication.

Frontend Configuration

Add these environment variables to the frontend (via .env or Vite config):

VITE_STYTCH_PROJECT_ID=your-project-id
VITE_STYTCH_PUBLIC_TOKEN=your-public-token

Stytch Setup

1. Create a Stytch account at https://stytch.com/
2. Create a new Consumer project
3. Configure allowed redirect URLs for your domains
4. Copy the Project ID and Public Token to your environment

Quick Start

1. Build the backend

dotnet build

2. Apply database migrations (SQLite for local dev)

dotnet ef database update --context SqliteContext --project PatchNotes.Data --startup-project PatchNotes.Api

3. Seed the database

cd PatchNotes.Sync
dotnet run -- --seed

4. Run the API

cd PatchNotes.Api
dotnet run

API available at: http://localhost:5031

5. Run the frontend

cd patchnotes-web
npm install
npm run dev

Frontend available at: http://localhost:5173

Testing

Test the API endpoints

# List packages
curl http://localhost:5031/api/packages

# Get releases (last 7 days)
curl http://localhost:5031/api/releases

# Get releases for specific packages
curl "http://localhost:5031/api/releases?packages=react,vue&days=30"

# Add a package
curl -X POST http://localhost:5031/api/packages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"npmName": "lodash"}'

# Get AI summary of a release
curl -X POST http://localhost:5031/api/releases/1/summarize

Run the sync

cd PatchNotes.Sync
dotnet run

Exit codes: 0=success, 1=partial failure, 2=fatal error

Seed sample data

cd PatchNotes.Sync
dotnet run -- --seed

Project Structure

PatchNotes/
├── PatchNotes.Api/           # Web API
├── PatchNotes.Data/          # Data layer
│   ├── Migrations/           # EF Core migrations
│   ├── GitHub/               # GitHub API client
│   └── Groq/                 # Groq LLM client
├── PatchNotes.Sync/          # Sync console app
└── patchnotes-web/           # React frontend
    └── src/
        ├── components/
        │   ├── package-picker/   # Package selection UI
        │   ├── releases/         # Release timeline components
        │   └── ui/               # Shared UI components
        ├── pages/                # Route pages
        ├── api/                  # TanStack Query hooks
        └── routes/               # TanStack Router config

Tech Stack

Backend:

• .NET 10 / ASP.NET Core
• Entity Framework Core + SQLite
• GitHub API integration

Frontend:

• React 18 + TypeScript
• TanStack Router (type-safe routing)
• TanStack Query (data fetching)
• Vite (build tool)

Development

Database Migrations

The project uses separate EF Core migrations for SQLite (development) and SQL Server (production).

Creating a new migration (when you change entity models):

# Set SQL Server connection string (required)
export ConnectionStrings__PatchNotes="Server=...;Database=...;User Id=...;Password=..."

# Generate migrations for both providers
./scripts/add-migration.sh MigrationName

This creates migrations in:

• PatchNotes.Data/Migrations/Sqlite/ - Local development
• PatchNotes.Data/Migrations/SqlServer/ - Production

Important: CI will fail if you change models without creating migrations. The has-pending-model-changes check ensures migrations are always committed with model changes.

For more details, see PatchNotes.Data/README.md.

Running Tests

Backend:

dotnet test PatchNotes.slnx

Frontend:

cd patchnotes-web
npm test

Code Quality

The project uses GitHub Actions for CI. All PRs must pass:

• dotnet build and dotnet test
• npm run lint and npm run format:check
• npm run build (includes TypeScript type checking)

Contributing

Code Style

Backend (.NET):

• Follow standard C# conventions
• Use async/await for I/O operations
• Keep controllers thin, business logic in services

Frontend (TypeScript):

• Use TypeScript strict mode
• Prefer TanStack Query for data fetching
• Follow the existing component structure

Pull Request Process

1. Create a feature branch from main
2. Make your changes with clear commit messages
3. Ensure all CI checks pass
4. Request review

License

MIT