How supernova3339/changerawr works
1. Overall shape
- This is a Next.js 16 App Router application in TypeScript, backed by Prisma + PostgreSQL.
- The repo is not just a UI: it combines the admin dashboard, public changelog sites, a large REST API, background jobs, and a standalone embeddable widget.
2. Main presentation surfaces
- app/dashboard/** is the authenticated product UI for managing projects, entries, domains, integrations, users, and system settings.
- app/changelog/** serves the public-facing changelog pages, including per-project pages, custom-domain pages, RSS feeds, and unsubscribe flows.
- app/(auth)/** contains the login/register/reset/setup flows.
- app/(email)/** contains email-related landing pages like unsubscribe confirmation.
3. API-first backend
- app/api/** is the central service layer, with route groups for auth, admin, projects, changelog, custom domains, analytics, AI, telemetry, system operations, integrations, and internal endpoints.
- The API is clearly the main orchestration boundary: UI screens, widgets, CLI flows, and external integrations all talk to these route handlers rather than directly touching persistence.
4. Data and persistence boundary
- Prisma schema is split by domain under prisma/schema/** and versioned through many migrations, showing a mature data model for auth, projects, changelog, integrations, custom domains, analytics, telemetry, and system configuration.
- prisma/seed.ts and the migration history indicate the database is the system of record for nearly everything, including security state and operational metadata.
5. Authentication and access control
- lib/auth/** implements custom auth primitives: JWTs, password auth, OAuth, SAML, passkeys/WebAuthn, API keys, CLI auth, invitations, and reset tokens.
- lib/api/permissions.ts and related middleware files enforce route-level permissions, making authorization a first-class backend boundary rather than a UI concern.
- The setup flow under app/api/setup/** and components/setup/** suggests onboarding is stateful and backed by persistent system configuration.
6. Changelog lifecycle
- Changelog content is managed as structured project data: entries, tags, versions, requests, scheduling, approval flows, catch-up summaries, search, and analytics.
- Public delivery happens through app/changelog/**, RSS routes, and widget APIs, while editors and management views live under components/changelog/** and app/dashboard/projects/[projectId]/changelog/**.
- lib/services/changelog/**, lib/services/request/**, and lib/services/search/** are the core domain services behind that lifecycle.
7. Embeddable widget subsystem
- The widget is a separate delivery target from the main app: source lives under widgets/**, while public/widget-bundle.js is the built artifact.
- app/api/integrations/widget/** and project widget management pages provide the configuration and runtime endpoints that the widget consumes.
- This is an important architectural boundary because the widget must remain lightweight, embeddable, and decoupled from the dashboard UI.
8. Custom domains and SSL automation
- lib/custom-domains/** plus app/api/custom-domains/** manage domain verification, DNS instructions, browser rules, and SSL mode toggles.
- app/.well-known/acme-challenge/** and app/api/acme/** support certificate issuance/renewal/revocation/status through ACME.
- lib/services/jobs/executors/ssl-renewal.executor.ts and cron endpoints under app/api/cron/** show that certificate maintenance is automated, not manual.
9. Integrations and outbound delivery
- The app integrates with GitHub, Slack, email, SAML/OAuth providers, and a Canny import path.
- Integration-specific logic is split between lib/services/github/**, lib/services/slack/**, lib/services/email/**, and project/admin API routes.
- Email templates in emails/** are part of the delivery pipeline for password resets, changelog notifications, approvals, rejections, and schedule publication.
10. AI and editor tooling
- AI features are managed through app/api/ai/**, app/api/admin/ai-settings/**, lib/utils/ai/**, and editor components such as title generation and assistant panels.
- The Markdown editor stack under components/markdown-editor/** and lib/services/core/markdown/** is a distinct subsystem, with custom extensions and safer rendering/keyboard handling.
- This suggests content authoring is a major product surface, not just a text box.
11. Background jobs and scheduled execution
- lib/services/jobs/** is the job orchestration layer, with executors for changelog publishing, SSL renewal, and telemetry delivery.
- These jobs connect the transactional app to time-based behavior: scheduled publication, periodic certificate renewal, and outbound telemetry.
- Cron endpoints and job services form the operational backbone for tasks that must run outside request/response traffic.
12. Observability and system operations
- Analytics is a first-class subsystem: app/api/analytics/**, lib/middleware/analytics.ts, and dashboard analytics views cover event capture and reporting.
- Telemetry, health, versioning, update status, and setup checks live under app/api/telemetry/**, app/api/health/**, and app/api/system/**.
- This indicates the app includes self-management features for production operation, not just user-facing functionality.
13. Deployment and runtime packaging
- Docker support is built in via Dockerfile, docker-compose*.yml, Caddyfile, nginx.conf, and startup scripts, so the app is intended to run as a containerized service.
- scripts/api/generateSwagger.*, public/swagger.json, and app/api-docs/route.ts show that the API documentation is generated and served as part of the product.
- scripts/maintenance/** and start:with-maintenance point to an explicit maintenance-mode runtime path.
14. Architectural takeaway
- The repository is best diagrammed as a single Next.js monolith with multiple product surfaces: authenticated dashboard, public changelog sites, API backend, widget distribution, and operational automation.
- The key boundaries are: UI vs API, auth vs domain services, main app vs widget, database vs scheduled jobs, and custom-domain/SSL infrastructure vs application logic.
Main entry points: dashboard Dashboard · schema Prisma schema · projects Project API · jobs Job runner
Components 22
App surfaces
Next.js routes and user-facing product surfaces
- Dashboard · Authenticated product interface for admins and project management
app/dashboard - Public changelog · Public changelog pages, RSS feeds, and unsubscribe flows
app/changelog - Auth flows · Login, register, reset, two-factor, OAuth callback, and setup screens
app/(auth) - Email pages · Email-related landing pages such as unsubscribe confirmation
app/(email)
API layer
Route handlers and service orchestration boundaries
- Auth API · Login, registration, tokens, passkeys, SAML, OAuth, CLI auth, and account security endpoints
app/api/auth - Project API · Project CRUD, changelog editing, tags, versions, imports, catch-up, CLI sync, and project integrations
app/api/projects - Changelog API · Entry, request, subscribe, unsubscribe, and domain verification endpoints
app/api/changelog - Domain API · Custom domain management, browser rules, DNS instructions, SSL controls, and verification
app/api/custom-domains - Admin API · System administration for users, config, API keys, OAuth, SAML, analytics, audit logs, and AI settings
app/api/admin - Integration API · Slack callbacks, widget runtime endpoints, and integration-specific delivery hooks
app/api/integrations - System API · Health, versioning, update status, telemetry, runtime config, and setup checks
app/api/system - ACME API · Certificate issuance, renewal, revocation, status, and DNS verification for SSL automation
app/api/acme
Domain services
Reusable backend logic organized by domain
- Auth core · JWTs, password auth, OAuth, SAML, passkeys, API keys, CLI auth, invitations, and reset tokens
lib/auth - Permissions · Route and action authorization middleware and permission rules
lib/api/permissions.ts - Changelog service · Changelog publishing, requests, RSS generation, search, and catch-up workflows
lib/services/changelog - Import pipeline · Canny import parsing, validation, processing, and markdown conversion
lib/services/projects/importing - Domain service · Custom domain verification, DNS guidance, SSL mode, and browser rules
lib/custom-domains
Data and ops
Persistence schema, jobs, automation, and deployment helpers
- Job runner · Scheduled job orchestration and executors for publishing, SSL renewal, and telemetry send
lib/services/jobs - Prisma schema · Versioned schema and migrations for auth, projects, changelog, integrations, domains, analytics, telemetry, and system config
prisma/schema - Runtime tools · Swagger generation, maintenance mode, widget build, and deployment helpers
scripts
Widget runtime
Embeddable widget source and generated bundle
- Widget source · Standalone embeddable changelog widget source
widgets - Widget bundle · Generated browser bundle served from the public directory
public/widget-bundle.js
Connections 26
- Dashboard → Project API: manages projects · Dashboard screens call project endpoints for CRUD, editing, and settings
- Dashboard → Admin API: admin ops · Admin screens use the admin API for system configuration and oversight
- Dashboard → Domain API: domain setup · Domain management views use custom-domain endpoints and SSL controls
- Dashboard → Integration API: integrations · Dashboard integration pages configure Slack, email, and widget delivery
- Public changelog → Changelog API: reads content · Public changelog pages load entries, subscriptions, and unsubscribe actions from the API
- Auth flows → Auth API: auth actions · Auth pages submit login, registration, reset, and two-factor flows to the auth API
- Email pages → Changelog API: unsubscribe · Email landing pages complete unsubscribe-related flows
- Auth API → Auth core: uses auth core · Auth handlers rely on shared JWT, token, OAuth, SAML, passkey, and password utilities
- Auth API → Permissions: guards routes · Authentication endpoints are protected by permission and middleware checks where needed
- Project API → Permissions: guards routes · Project operations enforce role and route-level permissions
- Admin API → Permissions: guards routes · Admin endpoints are restricted by authorization policy
- Changelog API → Changelog service: domain logic · Changelog route handlers delegate lifecycle work to shared changelog services
- Project API → Changelog service: publishing · Project changelog routes use shared changelog and request services
- Project API → Import pipeline: imports · Import endpoints route Canny and markdown ingestion through the importing pipeline
- Domain API → Domain service: domain logic · Domain endpoints wrap the custom-domain service layer
- ACME API → Domain service: ssl automation · ACME handlers coordinate certificate lifecycle through custom-domain SSL helpers
- Job runner → Domain service: renewals · Scheduled jobs trigger SSL renewal and certificate maintenance
- Job runner → Changelog service: publishes · Background executors handle scheduled changelog publication and notifications
- Prisma schema → Auth core: persists identities · The data model stores users, sessions, invitations, tokens, keys, and security state
- Prisma schema → Changelog service: persists content · Changelog entries, requests, tags, versions, schedules, and analytics are stored in Prisma-backed tables
- Prisma schema → Domain service: persists domains · Custom domains, verification, and SSL metadata are part of the persistent model
- Prisma schema → Job runner: job state · Jobs use database-backed operational state and configuration
- Runtime tools → Widget bundle: builds · Build scripts produce the distributable widget bundle
- Widget source → Widget bundle: bundles to · Widget source is packaged into the public browser artifact
- Integration API → Widget source: serves widget · Widget integration endpoints configure and power the embeddable runtime
- System API → Job runner: operates · System endpoints expose runtime status and update-related operational hooks