Skip to content
Kaddo Kaddo

Multirepo modules

Kaddo represents not only the main architecture repo, but also the secondary repos (frontend, backend, workers, infra…) as living modules of the same system.

Two levels of descriptor

  • kaddo module --init writes architecture/module.yml — a repo describing itself as a module (name, domains, contracts it exposes/consumes). Use this inside a secondary repo.
  • kaddo modules map writes .kaddo/modules.yml in the architecture repo — the system view, where each secondary repo is registered and given a knowledge structure under architecture/modules/<id>/.
Terminal window
kaddo modules map    # register a secondary repo as a module (interactive)
kaddo modules list   # list mapped modules

Mapping a module

kaddo modules map asks for a name, repository path (relative to the architecture repo), type (frontend · backend · worker · mobile · library · infrastructure · data · unknown), main technology, owner and related capabilities. It then:

  1. Records the module in .kaddo/modules.yml (upsert by id — re-mapping updates in place, never duplicates).
  2. Generates a knowledge structure from the central template registry (existing files are never overwritten — they are reported as kept):
architecture/modules/<id>/
  module-design.md
  stack.md
  security.md
  standards.md
  diagrams/.gitkeep
  adrs/.gitkeep

The generated .md files use the official module-design, module-stack, module-security and module-standards templates, with front matter prefilled from the module metadata — including a code: glob (<repoPath>/**):

---
type: module-design
module: storefront-web
name: Storefront Web
status: draft
owner: web-team
repoPath: ../frontend
moduleType: frontend
mainTechnology: Next.js
capabilities:
  - checkout
code:
  - ../frontend/**
---

The code: globs declare ownership consistently. Default kaddo guard still reads only the current repo’s git diff, but the opt-in kaddo guard --workspace also checks local mapped module repos and matches their changes against these globs — see guard → Workspace mode. It never clones or calls remote APIs.

Example: architecture-repo + frontend + backend + infra

Terminal window
# in the architecture repo
kaddo init
kaddo modules map   # Frontend  → ../frontend   (frontend, Next.js)
kaddo modules map   # Backend   → ../backend    (backend,  NestJS)
kaddo modules map   # Infra     → ../infra      (infrastructure, Terraform)
kaddo modules list

Result:

.kaddo/modules.yml
architecture/modules/
  frontend/{module-design,stack,security,standards}.md  diagrams/  adrs/
  backend/ {module-design,stack,security,standards}.md  diagrams/  adrs/
  infra/   {module-design,stack,security,standards}.md  diagrams/  adrs/

The generated templates are deliberately thin — refine each one with the matching Kaddo agent (module-design-agent, stack-agent, security-agent, standards-agent) in your LLM, using .kaddo/context-pack.md as input. The front matter and quality checklist come from the template registry, so module artifacts stay consistent with the rest of Kaddo.

Global vs module-level artifacts

  • Global (whole system): kaddo add standards|security|stack|git-strategy writes architecture/<topic>.md once for the system. See Standards, security & stack and Git strategy.
  • Module-level (per repo): architecture/modules/<id>/*.md, generated by kaddo modules map.

Kaddo never scans the secondary repos, never calls a Git/GitHub API, and never runs a security scan. It maps structure deterministically; your LLM agents do the interpretation.