Monodog: Monorepo Analytics and Health API

Overview

Monodog provides visual management and monitoring capabilities for packages in monorepos using pnpm and Turbo. It is distributed as an npm package that can be installed in any monorepo to automatically generate a web UI for package oversight.

This service is typically run locally or on a central server and power a dedicated frontend dashboard.

Technology Stack

| Component | Technology | Description | | ------------- | -------------------- | ----------------------------------------------------------------------------------------- | | Language | TypeScript & Node.js | Core language for runtime execution. | | Framework | Express.js, React | Express Handles all API routing and middleware and React for building the user interface. | | Styling | Tailwind CSS | Utility-first framework for responsive, modern, and aesthetic design. | | ORM | Prisma | Database layer for managing package and health status records. | |VCS | Github | Handles secure auth, automates Changeset PRs, and monitors CI/CD status. |

Prerequisites

You must have the following installed to run the service:

• Node.js: Version 18+ recommended
• Package Manager: pnpm

Getting Started

Install Package in Monorepo

Install monodog in a monorepo workspace root:

pnpm dlx @mindfiredigital/monodog

Run app using serve script:

cd ./monodog/ && npm run serve

Key API Endpoints

| Method | Route | Purpose | Persistence | | ------- | --------------------------- | --------------------------------------------------------------------------------------- | ------------------- | | GET | /api/packages | Retrieve all package metadata from the database. | Persistent | | POST | /api/packages/refresh | Trigger a full file scan of the monorepo and update/sync the database. | Triggers write | | GET | /api/packages/:name | Get detailed info, commits and health status for a package. | Persistent | | PUT | /api/packages/update-config| Update configuration for a package. | Triggers write | | GET | /api/health/packages | Fetch the latest health metrics (score, build status) for all packages. | Persistent | | POST | /api/health/refresh | Recalculate all package health metrics (build, lint, security) and update the database. | Triggers write | | GET | /api/commits/:packagePath | Fetch Git commit history for a specific package directory. | Persistent | | GET | /api/config/files | Scan the monorepo for essential configuration files (e.g., tsconfig, .eslintrc). | Generated runtime | | PUT | /api/config/files/:id | Update a configuration files (e.g., tsconfig, .eslintrc). | Generated runtime | | GET | /auth/login | Initiate GitHub OAuth 2.0 authentication flow. Redirects to GitHub for authorization. | Session creation | | GET | /auth/callback | Handle OAuth callback from GitHub with authorization code and validate state parameter. | Session persistence | | GET | /auth/me | Retrieve authenticated user profile. | Persistent | | GET | /auth/validate | Validate current session token status. | Persistent | | GET | /auth/logout | Invalidate session and clear authentication token. | Session termination | | POST | /auth/refresh | Extend session token validity period. | Session update | | GET | /api/publish/packages | Retrieve all packages available for publishing. | Persistent | | GET | /api/publish/changesets | Fetch existing unpublished changesets. | Persistent | | POST | /api/publish/changesets | Create a new changeset for selected packages. | Triggers write | | POST | /api/publish/preview | Preview the publish plan with version bumps and validation checks. | Generated runtime | | GET | /api/publish/status | Check if the repository is ready for publishing. | Persistent | | POST | /api/publish/trigger | Trigger the GitHub Actions release/publish workflow. | Triggers write |