Fleet Management: Multi-Repo & Monorepo Orchestration for Product Suites

Available from: v1.0.163

SaaS Factory now supports Fleet Management — a coordinated orchestration layer for enterprise teams building product suites across multiple repositories or within a single large monorepo. If your platform consists of a web app, mobile app, API service, and admin dashboard that share libraries and need to release in sync, Fleet Management is built for exactly that.

---

Core Concepts

Fleet

A Fleet is a named collection of SaaS Factory projects that form a product suite. Projects in a fleet are aware of each other: their agents share dependency context, their releases can be coordinated, and their shared libraries are versioned collectively.

Dependency Graph

Every fleet has a live dependency graph — a directed acyclic graph (DAG) where nodes are products and edges represent "product A consumes library / service from product B" relationships. The graph is derived from monorepoConfig and kept up to date automatically as agents open PRs.

Shared Library

A shared library is any package or service that more than one product in the fleet consumes. Shared libraries carry version constraints (exact pin or semver range) and are tracked in the Shared Library Registry.

---

Setting Up a Fleet

1. Configure monorepoConfig on Each Project

Navigate to Project Settings → Fleet Config for each product in your suite. The monorepoConfig editor accepts JSON and supports the following top-level keys:

{
  "fleetId": "acme-platform",
  "role": "consumer",
  "sharedLibraries": [
    { "name": "@acme/design-system", "version": "^2.0.0", "source": "acme-design-system" },
    { "name": "@acme/api-client",    "version": "3.1.4",   "source": "acme-api" }
  ],
  "dependsOn": ["acme-api"],
  "repoLayout": "multi-repo"
}

Field	Type	Description
fleetId	string	Identifier for the fleet this project belongs to. All projects sharing a fleetId form a fleet.
role	"producer" | "consumer" | "both"	Whether this project publishes shared libraries, consumes them, or both.
sharedLibraries	array	Libraries this project consumes, with source project slug and version constraint.
dependsOn	array	Other project slugs in the fleet that must release before this project can.
repoLayout	"mono-repo" | "multi-repo"	Informs agents how to navigate the codebase.

2. Open the Fleet View

Once two or more projects share a fleetId, a Fleet entry appears in the left sidebar under Development → Fleets. Select it to open the Fleet View.

3. Review the Dependency Graph

The dependency graph renders automatically. Nodes are colour-coded by health (green = healthy, amber = version drift detected, red = breaking change risk). Click any node to jump to that project's dashboard.

---

Coordinated Releases

Fleet Release Calendar

The Fleet Release Calendar (accessible from the Fleet View header) shows:

• Scheduled releases — releases queued by the autonomous pipeline for any product in the fleet.
• In-flight releases — releases currently running through CI/CD.
• Dependency ordering — a timeline view that enforces dependsOn constraints so nothing ships out of order.

How Coordinated Release Scheduling Works

1. When a product with role: producer cuts a release, the pipeline detects all downstream consumers via the dependency graph.
2. Each consumer project is queued for a compatibility check PR — an automated PR that bumps the shared library version and runs the full test suite.
3. If all compatibility checks pass, consumer releases are staged according to the Fleet Release Calendar order.
4. If a compatibility check fails, the fleet release is paused and an alert is raised before anything ships to production.

---

Shared Library Registry

The Shared Library Registry (Fleet View → Libraries tab) provides a centralised table of:

Column	Description
Library name	Package name as declared in monorepoConfig.
Current version	Latest version produced by the source project.
Consumers	All projects in the fleet that depend on this library.
Drift	Whether any consumer is pinned to an older version.
Changelog	Link to the library's release notes.

Automated Version Bump PRs

When the AI Architect agent merges a change that bumps a shared library's version in the producer project, it automatically:

1. Identifies all consumer projects from the registry.
2. Opens a coordinated PR in each consumer to update the version constraint.
3. Labels each PR with fleet-sync and links them together for traceability.

---

Agent Dependency Awareness

All agents (AI Architect, Beast Mode supercycles, PR pipeline) now read monorepoConfig at planning time. Practically, this means:

• Breaking-change detection: before planning a refactor that touches a shared interface, the agent checks which other products consume it and widens the change scope accordingly.
• Cross-repo context: agents can reference code patterns from sibling products in the fleet when generating implementations, avoiding divergence.
• Blast-radius estimation: feature decomposition tickets include an estimated blast radius (number of downstream products affected) so teams can prioritise review effort.

---

Limitations & Notes

• Fleet Management is designed for enterprise-tier projects. Contact support to enable the fleetId linking feature on your account.
• Circular dependencies in the dependency graph (A → B → A) are detected and blocked at config save time.
• repoLayout: "mono-repo" support assumes a standard workspace structure (npm/yarn/pnpm workspaces or Turborepo). Non-standard layouts may require additional repoLayout configuration options — these are on the roadmap.
• The monorepoConfig field was present in the database schema prior to this release but had no effect. Existing projects with a populated monorepoConfig column will have their config imported automatically on first Fleet View load.