Skip to content

README.md

Latest commit

 

History

History
341 lines (261 loc) · 20.4 KB

README.md

File metadata and controls

341 lines (261 loc) · 20.4 KB

LFX Changelog

A centralized changelog platform for LFX products. Provides a unified, public-facing timeline of product updates and an admin interface for teams to draft, review, and publish release notes with AI-assisted generation.

Features

Public

  • 📰 Changelog feed — filterable timeline of published entries across all LFX products
  • 📦 Per-product views — dedicated changelog pages for each of the 9 LFX products
  • 🔗 Pretty URLs — human-readable slugs (e.g., /entry/security-march-2026-patches)
  • 🔍 Full-text search — OpenSearch-powered with fuzzy matching, highlighting, and product faceting
  • 👁️ Changelog views — unseen-count tracking so external LFX apps can show notification badges
  • 🌙 Dark mode — light/dark dual-theme with system preference detection

Admin

  • 📊 Dashboard — overview of drafts, published entries, and recent activity
  • ✏️ Changelog editor — Markdown-based editor with live preview and category tagging
  • 🔐 Role-based access — super admin, product admin, and editor roles with per-product scoping

AI

  • 🤖 Changelog agent — Claude Agent SDK pipeline that auto-generates drafts from GitHub commits, merged PRs, and releases
  • 📝 Blog generation — monthly roundup blog posts synthesized from recent changelogs, with admin editor and public feed
  • 💬 Chat assistant — conversational AI that answers questions about changelog data with streaming responses

Integrations

  • 🐙 GitHub — GitHub App for repository tracking, release syncing, and webhook-driven changelog generation
  • 💬 Slack — share published changelogs to Slack channels with rich BlockKit messages
  • 🔌 MCP server — AI tool integration via the Model Context Protocol (Claude Desktop, Cursor, etc.)

Infrastructure

  • 🔑 Auth0 + API keys — OAuth sessions and scoped API keys for programmatic access (CI/CD, scripts, external tools)
  • ⚡ Server-side rendering — Angular SSR for fast initial loads and SEO
  • 📈 Observability — Datadog APM, RUM with session replay, and structured HTTP request logging
  • 🧪 E2E test suite — Playwright tests covering public pages, admin flows, RBAC, and API endpoints

Tech Stack

Layer Technology
Monorepo Turborepo + Yarn 4 workspaces
Frontend Angular 20 (standalone components, signals, zoneless)
Backend Express 5 (via Angular SSR server)
Database PostgreSQL 16
ORM Prisma 7 with driver adapter
Validation Zod 4 + OpenAPI 3.1 (Swagger UI at /docs)
Auth Auth0 (express-openid-connect)
Styling Tailwind CSS 4 (CSS-first config, custom components)
Testing Playwright (E2E, API)
Integration MCP SDK 1.x (Model Context Protocol)
CI/CD GitHub Actions, ArgoCD, Helm, GHCR

Prerequisites

  • Node.js >= 22
  • Yarn 4.12.0 (managed via Corepack)
  • Docker and Docker Compose (for PostgreSQL)

Getting Started

1. Clone and install

git clone https://github.com/linuxfoundation/lfx-changelog.git
cd lfx-changelog
corepack enable
yarn install

2. Set up environment variables

cp apps/lfx-changelog/.env.example apps/lfx-changelog/.env

Edit apps/lfx-changelog/.env with your values. See the Environment Variables section below for details.

3. Start the database

yarn docker:up

4. Run database migrations and seed

yarn db:generate
yarn db:migrate
yarn db:seed

5. Start the dev server

yarn start

The app runs at http://localhost:4204

Environment Variables

The server supports two ways to configure the database connection: a single DATABASE_URL connection string, or individual DB_* variables (which the server assembles at runtime via buildConnectionString). Provide one or the other.

Variable Required Description
DATABASE_URL Yes* PostgreSQL connection string (e.g., postgresql://changelog:changelog_dev@localhost:5432/lfx_changelog)
DB_HOST Yes* Database host (e.g., localhost)
DB_PORT No Database port (default: 5432)
DB_NAME Yes* Database name (e.g., lfx_changelog)
DB_USER Yes* Database user (e.g., changelog)
DB_PASSWORD Yes* Database password
AUTH0_CLIENT_ID Yes Auth0 application client ID
AUTH0_CLIENT_SECRET Yes Auth0 application client secret
AUTH0_ISSUER_BASE_URL Yes Auth0 tenant URL (e.g., https://your-tenant.auth0.com)
AUTH0_SECRET Yes Session encryption secret (min 32 characters)
BASE_URL Yes Application base URL (e.g., http://localhost:4204)
GITHUB_APP_ID No GitHub App ID for repository integration
GITHUB_PRIVATE_KEY No GitHub App RSA private key
GITHUB_WEBHOOK_SECRET No Secret for verifying GitHub webhook signatures (see Webhook Testing)
LITELLM_API_KEY No API key for AI changelog generation and AI chat
AI_API_URL No AI service endpoint URL (LiteLLM proxy)
OPENSEARCH_URL No OpenSearch endpoint for full-text search (e.g., https://search.example.com)
SLACK_CLIENT_ID No Slack OAuth client ID for Slack integration
SLACK_CLIENT_SECRET No Slack OAuth client secret
SLACK_TOKEN_ENCRYPTION_KEY No AES-256-GCM key for encrypting Slack tokens at rest (64 hex chars)
WEBHOOK_STATE_SECRET No HMAC secret for OAuth state CSRF protection (Slack + GitHub)
DATADOG_RUM_APPLICATION_ID No Datadog RUM application ID (client-side monitoring)
DATADOG_RUM_CLIENT_ID No Datadog RUM client token
NODE_ENV No development or production (default: development)
PORT No Server port (default: 4000)
LOG_LEVEL No Logging level: debug, info, warn, error (default: info)

*Provide either DATABASE_URL or the DB_HOST/DB_NAME/DB_USER/DB_PASSWORD group.

Scripts

Root (monorepo-level)

Script Description
yarn build Build all packages (shared + app)
yarn start Start the SSR server
yarn lint Run ESLint across all packages
yarn format Format all files with Prettier
yarn format:check Check formatting without writing
yarn markdownlint Lint markdown files
yarn markdownlint:fix Auto-fix markdown lint issues
yarn docker:up Start PostgreSQL via Docker Compose
yarn docker:down Stop PostgreSQL
yarn db:generate Generate Prisma client
yarn db:migrate Run database migrations
yarn db:seed Seed the database with sample data
yarn db:studio Open Prisma Studio (database GUI)
yarn test Run tests across all workspaces
yarn watch Build all packages in watch mode

App-level (apps/lfx-changelog)

Script Description
yarn start Angular dev server with live reload
yarn build:dev Development build
yarn build:prod Production build
yarn lint Lint the Angular app
yarn test Run Playwright E2E tests
yarn test:headed Run E2E tests with browser visible
yarn test:ui Run E2E tests in Playwright UI mode
yarn test:report Open the last Playwright HTML report

Project Structure

lfx-changelog/
├── apps/lfx-changelog/           # Angular 20 SSR application
│   ├── src/
│   │   ├── app/
│   │   │   ├── layouts/           # Public and admin layout shells
│   │   │   ├── modules/           # Feature modules (public + admin)
│   │   │   └── shared/            # Components, services, interfaces
│   │   ├── server/                # Express backend
│   │   │   ├── controllers/       # Request handlers
│   │   │   ├── services/          # Business logic + Prisma queries
│   │   │   ├── routes/            # Route definitions
│   │   │   ├── middleware/        # Auth, RBAC, validation, error handling
│   │   │   ├── swagger/           # OpenAPI path definitions
│   │   │   ├── helpers/           # Shared utilities (DB connection, etc.)
│   │   │   └── errors/            # Custom error classes
│   │   └── environments/          # Environment configs
│   ├── prisma/                    # Schema, migrations, seed
│   └── e2e/                       # Playwright E2E tests
│       ├── setup/                 # DB + auth setup projects
│       ├── helpers/               # Test utilities (API, DB, Docker, fixtures)
│       ├── pages/                 # Page Object Model classes
│       └── specs/                 # Test specs (public/, admin/, api/)
├── packages/shared/               # @lfx-changelog/shared (Zod schemas, types, enums)
├── packages/mcp-server/           # @lfx-changelog/mcp-server (MCP tools & resources)
├── charts/lfx-changelog/          # Helm chart for Kubernetes deployment
├── docs/                          # Additional documentation
├── docker-compose.yml             # Local PostgreSQL (dev + test)
├── Dockerfile                     # Multi-stage production build
└── turbo.json                     # Turborepo task config

Architecture

The application uses an Angular SSR server that also hosts the Express API backend. This single-server approach means:

  • Public API (/public/api/*) --- unauthenticated endpoints for reading published changelogs and products
  • Protected API (/api/*) --- authenticated endpoints for CRUD operations, supporting both OAuth sessions and API keys
  • API docs (/docs) --- interactive Swagger UI generated from Zod schemas via @asteasolutions/zod-to-openapi
  • MCP (/mcp) --- Model Context Protocol endpoint for AI tool integration (Streamable HTTP)
  • SSR --- Angular pages are server-rendered for all routes

Authentication

The API supports two authentication methods:

  • OAuth sessions --- browser-based login via Auth0 (session cookies)
  • API keys --- programmatic access via Authorization: Bearer lfx_... or X-API-Key: lfx_... headers

API keys are scoped (changelogs:read, changelogs:write, products:read, products:write) and enforce the same role checks as OAuth sessions. See API Authentication for details on creating keys, endpoint permissions, and usage examples.

Roles

Role Scope Permissions
super_admin Global Full access to all products, users, and settings
product_admin Per-product Manage changelogs and editors for assigned products
editor Per-product Create and edit changelogs for assigned products

Database

The PostgreSQL schema is managed by Prisma:

  • Product --- LFX products with activation status, Font Awesome icons, and optional GitHub App installation
  • ProductRepository --- GitHub repositories linked to products for release syncing and changelog generation
  • GitHubRelease --- release metadata synced from GitHub (tag, notes, author, publish date)
  • ChangelogEntry --- individual changelog entries with markdown content, versioning, slugs, and source tracking (manual or automated)
  • User --- users synced from Auth0 on first login
  • UserRoleAssignment --- maps users to roles, optionally scoped to a product
  • ApiKey --- scoped API keys for programmatic access, storing SHA-256 hashes with expiration and revocation tracking
  • ChatConversation / ChatMessage --- AI chat conversation history with tool call persistence
  • AutoChangelogLock --- distributed lock for concurrent auto-changelog generation across replicas
  • SlackIntegration / SlackChannel / SlackNotification --- Slack workspace connections, channel config, and delivery tracking

Useful commands

yarn db:studio          # Browse data in Prisma Studio
yarn db:migrate         # Apply pending migrations
yarn db:seed            # Reset and seed sample data

Testing

End-to-end tests use Playwright to verify the application from a user's perspective. Tests run against a real Angular SSR server backed by a test PostgreSQL database and authenticate through Auth0.

cd apps/lfx-changelog
yarn test               # Run all tests (headless)
yarn test:headed        # Run with browser visible
yarn test:ui            # Run with Playwright UI mode

Tests automatically start a test database container on port 5433, run migrations, seed data, and launch the dev server --- no manual setup needed.

The test suite covers:

  • Public pages --- changelog feed, product changelogs, theme toggle
  • Admin flows --- dashboard, changelog editor, product and user management
  • RBAC --- per-role access (super admin, product admin, editor, no-role)
  • API endpoints --- public and protected REST endpoints via direct HTTP

See docs/testing/e2e-testing.md for the full testing guide.

CI/CD

GitHub Actions runs on every push to main and on pull requests:

Job Description
License headers Verifies all source files include the required SPDX license header
Secret scan Scans for leaked secrets using Trufflehog
E2E tests Runs the full Playwright test suite against a test database

Docker Builds

Workflow Trigger Image Tag
docker-build-main.yml Push to main development
docker-build-tag.yml Git tag push (v*) Semver (e.g., 1.2.3)
docker-build-pr.yml PR with deploy-preview label changelog-pr-<number>

All images are pushed to GHCR (ghcr.io/linuxfoundation/lfx-changelog).

Deployment

The application deploys to Kubernetes via ArgoCD:

  • Dev: merge to main builds image tagged development --- ArgoCD syncs and runs the migration Job before updating pods
  • Prod: git tag push builds a versioned image + publishes a signed Helm chart (with Cosign and SLSA provenance) --- ArgoCD syncs the new chart

Database migrations run automatically as a Helm pre-upgrade Job. See docs/database-migrations.md for details.

The production container runs as a non-root user on port 4000.

PR Deploy Previews

Adding the deploy-preview label to a PR builds and pushes a branch-specific image. ArgoCD provisions an isolated namespace (changelog-pr-<number>) with its own deployment. The preview is removed when the PR is closed or the label is removed.

Documentation

Document Description
AI Chat Agentic chat assistant, SSE streaming, conversation persistence
API Authentication API keys, OAuth sessions, scopes, and usage examples
Changelog Agent Claude Agent SDK pipeline, MCP tools, job tracking, webhooks
Changelog Views Unseen-count tracking API for external LFX product apps
Database Migrations Automated (CI/CD) and manual migration workflows
GitHub Integration GitHub App, repo tracking, release sync, auto-changelog, webhooks
MCP Server MCP tools, resources, and client setup
Observability Datadog APM, RUM, session replay, HTTP logging, pretty URLs
OpenSearch Full-text search, indexing, reindexing, MCP search tools
Remote Database Access Connecting to RDS via kubectl port-forward
Slack Integration OAuth flow, token encryption, posting changelogs to Slack
E2E Testing Test architecture, patterns, and how to add tests
Webhook Testing Testing GitHub release webhooks locally
Contributing License headers, code style, commit conventions
Security Vulnerability reporting

Contributing

See CONTRIBUTING.md for guidelines on submitting changes, license header requirements, and commit conventions.

License

MIT --- Copyright The Linux Foundation and each contributor to LFX.