How mohammadkarimi/prly works
1. Repository purpose
- Prly is a TypeScript CLI that turns merged pull requests from a GitHub repo into a daily summary.
- The core pipeline is: load config → fetch merged PRs → optionally filter by owned directories → optionally generate an AI summary → optionally deliver the result to external channels.
2. Top-level execution model
- The main entrypoint is src/cli.ts, which wires the command-line interface to the command handlers under src/commands/.
- The repo supports multiple commands, but the primary workflow is centered on run, with separate config and listing commands for setup and inspection.
3. Command layer
- src/commands/summary.ts appears to be the main orchestration command for the run flow.
- The other commands are configuration-oriented or diagnostic: list, list-all, and config/*.
- This layer is responsible for parsing options like date range, AI enablement, and delivery targets, then delegating to providers.
4. Configuration boundary
- src/config/index.ts manages the app configuration read from ~/.prly.config.json.
- The configuration is the primary boundary between user setup and runtime behavior: GitHub repo identity, module filters, AI credentials, SMTP settings, webhook URLs, and Teams integration live here.
- The README indicates secrets are stored locally in that config file rather than in environment variables, which makes config loading a central subsystem.
5. GitHub data acquisition
- src/providers/github.ts is the integration point for retrieving repository data.
- It supports GitHub API access using a configured token or falling back to GitHub CLI authentication (gh auth token) when no token is present.
- This provider is responsible for finding merged PRs in a date window and likely fetching the changed files needed for module filtering.
6. Module-based filtering
- The repository has a distinct concept of “owned modules” defined by directory prefixes in github.filterModules.
- The data flow here is: fetch merged PRs → inspect changed files per PR → include only PRs touching configured paths.
- The --verbose option in the CLI exposes this boundary by printing file-level changes while filtering, which is useful for validating the module map.
7. AI summarization layer
- src/providers/openai.ts encapsulates the OpenAI integration used when --ai is enabled.
- The summary generation is not just a free-form prompt; the README describes a structured release-notes style output with sections such as Problem / Change / Result.
- llmOptions in config control the language and optional custom system prompt, so this provider is effectively the transformation stage from raw PR metadata into human-readable narrative.
8. Delivery/output integrations
- Delivery is split into separate providers under src/providers/: email.ts, msTeams.ts, and webhook.ts.
- These are opt-in sinks at the end of the pipeline, meaning the same summary payload can be rendered differently depending on the target.
- MS Teams is especially notable because the app can send either a plain MessageCard or a richer Adaptive Card when AI output is available.
9. Formatting and data-shaping helpers
- src/types.ts defines the shared domain shapes used across commands and providers, keeping PR, summary, and config data consistent.
- src/utils/date-helper.ts likely standardizes default date ranges such as “yesterday to today,” which are used by the CLI defaults and listing commands.
- obfuscate.js suggests there is a small auxiliary build or packaging step to protect or transform parts of the distribution, though it is not part of the runtime data flow.
10. GitHub Action packaging
- action.yml exposes the same functionality as a reusable GitHub Action, so the architecture has both a local CLI and an automation/runtime variant.
- The Action inputs mirror the CLI/config concepts: repo identity, date range, filters, AI, email, Teams, and webhook delivery.
- This means the core logic is designed to be reusable across interactive terminal use and CI-driven scheduled execution.
11. Build and release mechanics
- The repo is TypeScript-based and uses vite.config.ts, tsconfig.json, and package-lock.json for build/package reproducibility.
- .github/workflows/publish.yml indicates an automated publish/release path, likely for the npm package and/or action release process.
- From an architecture perspective, build-time tooling is separate from runtime behavior; the actual product boundary is the compiled CLI/action bundle.
12. External system dependencies
- Prly depends on GitHub for PR metadata, OpenAI for summarization, SMTP for email delivery, and webhook endpoints for Teams/generic posting.
- These are cleanly separated by provider modules, so each external integration is isolated behind its own boundary rather than mixed into the command layer.
- For architecture diagrams, the most important flows to show are: CLI/config → GitHub fetch → optional filter → optional OpenAI summarize → optional delivery providers.
Main entry points: summary.ts Run flow · index.ts Config · github.ts GitHub · openai.ts AI summary
Components 18
Runtime pipeline
CLI execution flow from command entry through data fetch, transform, and delivery.
- CLI · Main command-line entry that wires argv to command handlers.
src/cli.ts - Run flow · Primary orchestration command for the daily summary workflow.
src/commands/summary.ts - Config · Loads and manages runtime configuration from the local config file.
src/config/index.ts - Dates · Standardizes default and derived date ranges for commands.
src/utils/date-helper.ts - Domain types · Shared shapes for PRs, summaries, config, and provider data.
src/types.ts - Module filter · Keeps only PRs that touch configured owned directory prefixes.
External systems
Third-party services and output channels used by the app.
- GitHub · Fetches merged PRs and related file metadata from GitHub.
src/providers/github.ts - AI summary · Turns PR metadata into structured release-note style prose.
src/providers/openai.ts - Email · Delivers the final summary through SMTP email.
src/providers/email.ts - Teams · Sends summary payloads to Microsoft Teams as cards.
src/providers/msTeams.ts - Webhook · Posts the summary to generic webhook endpoints.
src/providers/webhook.ts
Packaging
Action and release/build surfaces that reuse the same core logic.
- GitHub Action · Reusable Action surface that exposes the same workflow in CI.
action.yml - Publish flow · Automated workflow for packaging and publishing releases.
.github/workflows/publish.yml - Obfuscate · Auxiliary packaging step used during distribution.
obfuscate.js - Build config · Defines the TypeScript build and bundle setup.
vite.config.ts - TS config · TypeScript compiler settings for the project.
tsconfig.json - Package · Dependency lockfile and package metadata for reproducible installs.
package-lock.json - Docs · Explains the workflow, configuration, and usage model.
README.md
Connections 22
- CLI → Run flow: dispatches · Routes CLI subcommands to the summary workflow.
- Run flow → Config: loads · Reads config before executing the pipeline.
- Run flow → Dates: defaults · Computes default date windows and range handling.
- Run flow → GitHub: fetches · Retrieves merged pull requests and file changes.
- GitHub → Module filter: feeds · PRs flow into path-based module filtering.
- Module filter → AI summary: optional summarize · Filtered PRs may be transformed into AI-generated release notes.
- Run flow → AI summary: enabled by · AI summarization is invoked when requested.
- Run flow → Email: delivers · Optional email delivery of the final summary.
- Run flow → Teams: delivers · Optional Microsoft Teams delivery of the final summary.
- Run flow → Webhook: delivers · Optional webhook delivery of the final summary.
- Run flow → Domain types: uses · Shared domain models constrain command/provider data.
- Config → GitHub: auth config · Supplies repo identity and GitHub credentials.
- Config → AI summary: ai config · Supplies model settings, language, and prompts.
- Config → Email: smtp config · Supplies mail server and recipient settings.
- Config → Teams: channel config · Supplies Teams delivery settings and card mode.
- Config → Webhook: endpoint config · Supplies webhook URLs and payload options.
- GitHub Action → Run flow: reuses · Action entry invokes the same core workflow as the CLI.
- Publish flow → Package: publishes · Release automation depends on package artifacts.
- Build config → Package: bundles · Build tooling produces distributable output from the package.
- TS config → Package: compiles · Compiler settings shape the TypeScript build.
- Docs → Config: documents · Describes config file boundaries and secrets handling.
- Docs → Run flow: documents · Explains the main run workflow and options.