# supernova3339/changerawr architecture

> Architecture diagram of the GitHub repository supernova3339/changerawr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supernova3339/changerawr
- Repository: https://github.com/supernova3339/changerawr

## Overview

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: [`app/dashboard`](https://github.com/supernova3339/changerawr/tree/master/app/dashboard) (Dashboard), [`prisma/schema`](https://github.com/supernova3339/changerawr/tree/master/prisma/schema) (Prisma schema), [`app/api/projects`](https://github.com/supernova3339/changerawr/tree/master/app/api/projects) (Project API), [`lib/services/jobs`](https://github.com/supernova3339/changerawr/tree/master/lib/services/jobs) (Job runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App surfaces"]
  node_node_dashboard["Dashboard<br/>app UI"]
  node_node_changelog_public["Public changelog<br/>app UI"]
  node_node_auth_ui["Auth flows<br/>app UI"]
  node_node_email_ui["Email pages<br/>app UI"]
end

subgraph group_group_api["API layer"]
  node_node_api_auth["Auth API<br/>route handlers"]
  node_node_api_projects["Project API<br/>route handlers"]
  node_node_api_changelog["Changelog API<br/>route handlers"]
  node_node_api_domains["Domain API<br/>route handlers"]
  node_node_api_admin["Admin API<br/>route handlers"]
  node_node_api_integrations["Integration API<br/>route handlers"]
  node_node_api_system["System API<br/>route handlers"]
  node_node_api_acme["ACME API<br/>route handlers"]
end

subgraph group_group_services["Domain services"]
  node_node_auth_lib["Auth core"]
  node_node_permissions["Permissions<br/>policy layer<br/>[permissions.ts]"]
  node_node_changelog_service["Changelog service<br/>domain service"]
  node_node_importing["Import pipeline<br/>domain service"]
  node_node_custom_domains["Domain service"]
end

subgraph group_group_data["Data and ops"]
  node_node_jobs["Job runner<br/>background jobs"]
  node_node_prisma[("Prisma schema<br/>data model")]
  node_node_scripts["Runtime tools<br/>build/runtime scripts"]
end

subgraph group_group_widget["Widget runtime"]
  node_node_widget["Widget source<br/>embed runtime"]
  node_node_widget_bundle["Widget bundle<br/>built asset<br/>[widget-bundle.js]"]
end

node_node_dashboard -->|"manages projects"| node_node_api_projects
node_node_dashboard -->|"admin ops"| node_node_api_admin
node_node_dashboard -->|"domain setup"| node_node_api_domains
node_node_dashboard -->|"integrations"| node_node_api_integrations
node_node_changelog_public -->|"reads content"| node_node_api_changelog
node_node_auth_ui -->|"auth actions"| node_node_api_auth
node_node_email_ui -->|"unsubscribe"| node_node_api_changelog
node_node_api_auth -->|"uses auth core"| node_node_auth_lib
node_node_api_auth -->|"guards routes"| node_node_permissions
node_node_api_projects -->|"guards routes"| node_node_permissions
node_node_api_admin -->|"guards routes"| node_node_permissions
node_node_api_changelog -->|"domain logic"| node_node_changelog_service
node_node_api_projects -->|"publishing"| node_node_changelog_service
node_node_api_projects -->|"imports"| node_node_importing
node_node_api_domains -->|"domain logic"| node_node_custom_domains
node_node_api_acme -->|"ssl automation"| node_node_custom_domains
node_node_jobs -->|"renewals"| node_node_custom_domains
node_node_jobs -->|"publishes"| node_node_changelog_service
node_node_prisma -.->|"persists identities"| node_node_auth_lib
node_node_prisma -.->|"persists content"| node_node_changelog_service
node_node_prisma -.->|"persists domains"| node_node_custom_domains
node_node_prisma -.->|"job state"| node_node_jobs
node_node_scripts -->|"builds"| node_node_widget_bundle
node_node_widget -->|"bundles to"| node_node_widget_bundle
node_node_api_integrations -->|"serves widget"| node_node_widget
node_node_api_system -->|"operates"| node_node_jobs

click node_node_dashboard "https://github.com/supernova3339/changerawr/tree/master/app/dashboard"
click node_node_changelog_public "https://github.com/supernova3339/changerawr/tree/master/app/changelog"
click node_node_auth_ui "https://github.com/supernova3339/changerawr/tree/master/app/(auth)"
click node_node_email_ui "https://github.com/supernova3339/changerawr/tree/master/app/(email)"
click node_node_api_auth "https://github.com/supernova3339/changerawr/tree/master/app/api/auth"
click node_node_api_projects "https://github.com/supernova3339/changerawr/tree/master/app/api/projects"
click node_node_api_changelog "https://github.com/supernova3339/changerawr/tree/master/app/api/changelog"
click node_node_api_domains "https://github.com/supernova3339/changerawr/tree/master/app/api/custom-domains"
click node_node_api_admin "https://github.com/supernova3339/changerawr/tree/master/app/api/admin"
click node_node_api_integrations "https://github.com/supernova3339/changerawr/tree/master/app/api/integrations"
click node_node_api_system "https://github.com/supernova3339/changerawr/tree/master/app/api/system"
click node_node_api_acme "https://github.com/supernova3339/changerawr/tree/master/app/api/acme"
click node_node_auth_lib "https://github.com/supernova3339/changerawr/tree/master/lib/auth"
click node_node_permissions "https://github.com/supernova3339/changerawr/blob/master/lib/api/permissions.ts"
click node_node_changelog_service "https://github.com/supernova3339/changerawr/tree/master/lib/services/changelog"
click node_node_importing "https://github.com/supernova3339/changerawr/tree/master/lib/services/projects/importing"
click node_node_custom_domains "https://github.com/supernova3339/changerawr/tree/master/lib/custom-domains"
click node_node_jobs "https://github.com/supernova3339/changerawr/tree/master/lib/services/jobs"
click node_node_prisma "https://github.com/supernova3339/changerawr/tree/master/prisma/schema"
click node_node_scripts "https://github.com/supernova3339/changerawr/tree/master/scripts"
click node_node_widget "https://github.com/supernova3339/changerawr/tree/master/widgets"
click node_node_widget_bundle "https://github.com/supernova3339/changerawr/blob/master/public/widget-bundle.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_dashboard,node_node_changelog_public,node_node_auth_ui,node_node_email_ui toneBlue
class node_node_api_auth,node_node_api_projects,node_node_api_changelog,node_node_api_domains,node_node_api_admin,node_node_api_integrations,node_node_api_system,node_node_api_acme toneAmber
class node_node_auth_lib,node_node_permissions,node_node_changelog_service,node_node_importing,node_node_custom_domains toneMint
class node_node_jobs,node_node_prisma,node_node_scripts toneRose
class node_node_widget,node_node_widget_bundle toneIndigo
```

## Components

### App surfaces

Next.js routes and user-facing product surfaces

- [Dashboard](https://github.com/supernova3339/changerawr/tree/master/app/dashboard): app UI · Authenticated product interface for admins and project management · `app/dashboard`
- [Public changelog](https://github.com/supernova3339/changerawr/tree/master/app/changelog): app UI · Public changelog pages, RSS feeds, and unsubscribe flows · `app/changelog`
- [Auth flows](https://github.com/supernova3339/changerawr/tree/master/app/(auth)): app UI · Login, register, reset, two-factor, OAuth callback, and setup screens · `app/(auth)`
- [Email pages](https://github.com/supernova3339/changerawr/tree/master/app/(email)): app UI · Email-related landing pages such as unsubscribe confirmation · `app/(email)`

### API layer

Route handlers and service orchestration boundaries

- [Auth API](https://github.com/supernova3339/changerawr/tree/master/app/api/auth): route handlers · Login, registration, tokens, passkeys, SAML, OAuth, CLI auth, and account security endpoints · `app/api/auth`
- [Project API](https://github.com/supernova3339/changerawr/tree/master/app/api/projects): route handlers · Project CRUD, changelog editing, tags, versions, imports, catch-up, CLI sync, and project integrations · `app/api/projects`
- [Changelog API](https://github.com/supernova3339/changerawr/tree/master/app/api/changelog): route handlers · Entry, request, subscribe, unsubscribe, and domain verification endpoints · `app/api/changelog`
- [Domain API](https://github.com/supernova3339/changerawr/tree/master/app/api/custom-domains): route handlers · Custom domain management, browser rules, DNS instructions, SSL controls, and verification · `app/api/custom-domains`
- [Admin API](https://github.com/supernova3339/changerawr/tree/master/app/api/admin): route handlers · System administration for users, config, API keys, OAuth, SAML, analytics, audit logs, and AI settings · `app/api/admin`
- [Integration API](https://github.com/supernova3339/changerawr/tree/master/app/api/integrations): route handlers · Slack callbacks, widget runtime endpoints, and integration-specific delivery hooks · `app/api/integrations`
- [System API](https://github.com/supernova3339/changerawr/tree/master/app/api/system): route handlers · Health, versioning, update status, telemetry, runtime config, and setup checks · `app/api/system`
- [ACME API](https://github.com/supernova3339/changerawr/tree/master/app/api/acme): route handlers · Certificate issuance, renewal, revocation, status, and DNS verification for SSL automation · `app/api/acme`

### Domain services

Reusable backend logic organized by domain

- [Auth core](https://github.com/supernova3339/changerawr/tree/master/lib/auth): library · JWTs, password auth, OAuth, SAML, passkeys, API keys, CLI auth, invitations, and reset tokens · `lib/auth`
- [Permissions](https://github.com/supernova3339/changerawr/blob/master/lib/api/permissions.ts): policy layer · Route and action authorization middleware and permission rules · `lib/api/permissions.ts`
- [Changelog service](https://github.com/supernova3339/changerawr/tree/master/lib/services/changelog): domain service · Changelog publishing, requests, RSS generation, search, and catch-up workflows · `lib/services/changelog`
- [Import pipeline](https://github.com/supernova3339/changerawr/tree/master/lib/services/projects/importing): domain service · Canny import parsing, validation, processing, and markdown conversion · `lib/services/projects/importing`
- [Domain service](https://github.com/supernova3339/changerawr/tree/master/lib/custom-domains): 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](https://github.com/supernova3339/changerawr/tree/master/lib/services/jobs): background jobs · Scheduled job orchestration and executors for publishing, SSL renewal, and telemetry send · `lib/services/jobs`
- [Prisma schema](https://github.com/supernova3339/changerawr/tree/master/prisma/schema): data model · Versioned schema and migrations for auth, projects, changelog, integrations, domains, analytics, telemetry, and system config · `prisma/schema`
- [Runtime tools](https://github.com/supernova3339/changerawr/tree/master/scripts): build/runtime scripts · Swagger generation, maintenance mode, widget build, and deployment helpers · `scripts`

### Widget runtime

Embeddable widget source and generated bundle

- [Widget source](https://github.com/supernova3339/changerawr/tree/master/widgets): embed runtime · Standalone embeddable changelog widget source · `widgets`
- [Widget bundle](https://github.com/supernova3339/changerawr/blob/master/public/widget-bundle.js): built asset · Generated browser bundle served from the public directory · `public/widget-bundle.js`

## Connections

- 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