# mohammadkarimi/prly architecture

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

- Interactive diagram: https://gitdiagram.com/mohammadkarimi/prly
- Repository: https://github.com/mohammadkarimi/prly

## Overview

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: [`src/commands/summary.ts`](https://github.com/mohammadkarimi/prly/blob/main/src/commands/summary.ts) (Run flow), [`src/config/index.ts`](https://github.com/mohammadkarimi/prly/blob/main/src/config/index.ts) (Config), [`src/providers/github.ts`](https://github.com/mohammadkarimi/prly/blob/main/src/providers/github.ts) (GitHub), [`src/providers/openai.ts`](https://github.com/mohammadkarimi/prly/blob/main/src/providers/openai.ts) (AI summary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime pipeline"]
  node_cli["CLI<br/>entrypoint<br/>[cli.ts]"]
  node_summary_cmd["Run flow<br/>command<br/>[summary.ts]"]
  node_config_mod["Config<br/>settings<br/>[index.ts]"]
  node_date_helper["Dates<br/>[date-helper.ts]"]
  node_types_mod["Domain types<br/>schema<br/>[types.ts]"]
  node_filter_stage{{"Module filter<br/>transform"}}
end

subgraph group_integrations["External systems"]
  node_github_provider[("GitHub<br/>source<br/>[github.ts]")]
  node_openai_provider["AI summary<br/>transform<br/>[openai.ts]"]
  node_email_provider["Email<br/>sink<br/>[email.ts]"]
  node_teams_provider["Teams<br/>sink<br/>[msTeams.ts]"]
  node_webhook_provider["Webhook<br/>sink<br/>[webhook.ts]"]
end

subgraph group_packaging["Packaging"]
  node_action_file["GitHub Action<br/>automation entry<br/>[action.yml]"]
  node_publish_workflow["Publish flow<br/>release automation<br/>[publish.yml]"]
  node_obfuscate["Obfuscate<br/>build helper<br/>[obfuscate.js]"]
  node_vite["Build config<br/>build tool<br/>[vite.config.ts]"]
  node_tsconfig["TS config<br/>build config<br/>[tsconfig.json]"]
  node_package["Package<br/>[package-lock.json]"]
  node_readme["Docs<br/>documentation<br/>[README.md]"]
end

node_cli -->|"dispatches"| node_summary_cmd
node_summary_cmd -->|"loads"| node_config_mod
node_summary_cmd -->|"defaults"| node_date_helper
node_summary_cmd -->|"fetches"| node_github_provider
node_github_provider -->|"feeds"| node_filter_stage
node_filter_stage -->|"optional summarize"| node_openai_provider
node_summary_cmd -.->|"enabled by"| node_openai_provider
node_summary_cmd -->|"delivers"| node_email_provider
node_summary_cmd -->|"delivers"| node_teams_provider
node_summary_cmd -->|"delivers"| node_webhook_provider
node_summary_cmd -->|"uses"| node_types_mod
node_config_mod -->|"auth config"| node_github_provider
node_config_mod -->|"ai config"| node_openai_provider
node_config_mod -->|"smtp config"| node_email_provider
node_config_mod -->|"channel config"| node_teams_provider
node_config_mod -->|"endpoint config"| node_webhook_provider
node_action_file -->|"reuses"| node_summary_cmd
node_publish_workflow -.->|"publishes"| node_package
node_vite -.->|"bundles"| node_package
node_tsconfig -.->|"compiles"| node_package
node_readme -.->|"documents"| node_config_mod
node_readme -.->|"documents"| node_summary_cmd

click node_cli "https://github.com/mohammadkarimi/prly/blob/main/src/cli.ts"
click node_summary_cmd "https://github.com/mohammadkarimi/prly/blob/main/src/commands/summary.ts"
click node_config_mod "https://github.com/mohammadkarimi/prly/blob/main/src/config/index.ts"
click node_date_helper "https://github.com/mohammadkarimi/prly/blob/main/src/utils/date-helper.ts"
click node_types_mod "https://github.com/mohammadkarimi/prly/blob/main/src/types.ts"
click node_github_provider "https://github.com/mohammadkarimi/prly/blob/main/src/providers/github.ts"
click node_openai_provider "https://github.com/mohammadkarimi/prly/blob/main/src/providers/openai.ts"
click node_email_provider "https://github.com/mohammadkarimi/prly/blob/main/src/providers/email.ts"
click node_teams_provider "https://github.com/mohammadkarimi/prly/blob/main/src/providers/msTeams.ts"
click node_webhook_provider "https://github.com/mohammadkarimi/prly/blob/main/src/providers/webhook.ts"
click node_action_file "https://github.com/mohammadkarimi/prly/blob/main/action.yml"
click node_publish_workflow "https://github.com/mohammadkarimi/prly/blob/main/.github/workflows/publish.yml"
click node_obfuscate "https://github.com/mohammadkarimi/prly/blob/main/obfuscate.js"
click node_vite "https://github.com/mohammadkarimi/prly/blob/main/vite.config.ts"
click node_tsconfig "https://github.com/mohammadkarimi/prly/blob/main/tsconfig.json"
click node_package "https://github.com/mohammadkarimi/prly/blob/main/package-lock.json"
click node_readme "https://github.com/mohammadkarimi/prly/blob/main/README.md"

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_cli,node_summary_cmd,node_config_mod,node_date_helper,node_types_mod,node_filter_stage toneBlue
class node_github_provider,node_openai_provider,node_email_provider,node_teams_provider,node_webhook_provider toneAmber
class node_action_file,node_publish_workflow,node_obfuscate,node_vite,node_tsconfig,node_package,node_readme toneMint
```

## Components

### Runtime pipeline

CLI execution flow from command entry through data fetch, transform, and delivery.

- [CLI](https://github.com/mohammadkarimi/prly/blob/main/src/cli.ts): entrypoint · Main command-line entry that wires argv to command handlers. · `src/cli.ts`
- [Run flow](https://github.com/mohammadkarimi/prly/blob/main/src/commands/summary.ts): command · Primary orchestration command for the daily summary workflow. · `src/commands/summary.ts`
- [Config](https://github.com/mohammadkarimi/prly/blob/main/src/config/index.ts): settings · Loads and manages runtime configuration from the local config file. · `src/config/index.ts`
- [Dates](https://github.com/mohammadkarimi/prly/blob/main/src/utils/date-helper.ts): utility · Standardizes default and derived date ranges for commands. · `src/utils/date-helper.ts`
- [Domain types](https://github.com/mohammadkarimi/prly/blob/main/src/types.ts): schema · Shared shapes for PRs, summaries, config, and provider data. · `src/types.ts`
- **Module filter**: transform · Keeps only PRs that touch configured owned directory prefixes.

### External systems

Third-party services and output channels used by the app.

- [GitHub](https://github.com/mohammadkarimi/prly/blob/main/src/providers/github.ts): source · Fetches merged PRs and related file metadata from GitHub. · `src/providers/github.ts`
- [AI summary](https://github.com/mohammadkarimi/prly/blob/main/src/providers/openai.ts): transform · Turns PR metadata into structured release-note style prose. · `src/providers/openai.ts`
- [Email](https://github.com/mohammadkarimi/prly/blob/main/src/providers/email.ts): sink · Delivers the final summary through SMTP email. · `src/providers/email.ts`
- [Teams](https://github.com/mohammadkarimi/prly/blob/main/src/providers/msTeams.ts): sink · Sends summary payloads to Microsoft Teams as cards. · `src/providers/msTeams.ts`
- [Webhook](https://github.com/mohammadkarimi/prly/blob/main/src/providers/webhook.ts): sink · 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](https://github.com/mohammadkarimi/prly/blob/main/action.yml): automation entry · Reusable Action surface that exposes the same workflow in CI. · `action.yml`
- [Publish flow](https://github.com/mohammadkarimi/prly/blob/main/.github/workflows/publish.yml): release automation · Automated workflow for packaging and publishing releases. · `.github/workflows/publish.yml`
- [Obfuscate](https://github.com/mohammadkarimi/prly/blob/main/obfuscate.js): build helper · Auxiliary packaging step used during distribution. · `obfuscate.js`
- [Build config](https://github.com/mohammadkarimi/prly/blob/main/vite.config.ts): build tool · Defines the TypeScript build and bundle setup. · `vite.config.ts`
- [TS config](https://github.com/mohammadkarimi/prly/blob/main/tsconfig.json): build config · TypeScript compiler settings for the project. · `tsconfig.json`
- [Package](https://github.com/mohammadkarimi/prly/blob/main/package-lock.json): package metadata · Dependency lockfile and package metadata for reproducible installs. · `package-lock.json`
- [Docs](https://github.com/mohammadkarimi/prly/blob/main/README.md): documentation · Explains the workflow, configuration, and usage model. · `README.md`

## Connections

- 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.
