RFC: Multiple Projects

[davydkov]

Important

Below is a proposal that may be revised entirely after receiving your feedback.
And if you’d like to contribute, join our Discord

Important

UPDATE - v1.26 introduced initial support

At the moment both CLI and Vscode extension crawl workspace folder for likec4 DSLs.
This works for most cases, but limits us if we have monorepos or projects in different folders.
Workarounds with syminks are temporary solution.
see #962 and #1627

We may introduce projects by creating config files (similar to package.json / tsconfig).

Assume we have these structure

.
├── teamA/
│   ├── projectA1/
│   │   ├── .likec4rc
│   │   ├── spec.c4
│   │   └── model.c4
│   └── projectA2/
│       ├── .likec4rc
│       ├── spec.c4
│       └── model.c4  
└── teamB/
    └── projectB1/
        ├── .likec4rc
        ├── spec.c4
        └── model.c4

If we start CLI from the root (or open vscode) - Likec4 will recognize separate projects.
Each project is isolated, has it’s own specs, model and views, and does not interfere with others.
Sure, we want to reference elements between.

Assume we have model in projectA2

// teamA/projectA2/model.c4
model {
  service srv1 {
    compoonent api
  }
}

To reference projectA2 from projectB1 we define in project config:

// teamB/projectB1/.likec4rc
{
  name: "projectB1",
  imports: {
    a2: "../../teamA/projectA2"
  }
}

Now, in the model of projectB1 we reference projectA2 via a2

// teamB/projectB1/model.c4
model {
  service srv2 {
    -> a2.srv1.api
  }
}

To encapsulate internals and restrict what can be referenced from the outside, project config allows to define “exports” (and give aliases)

// teamA/projectA1/.likec4rc
{
  name: "projectA1",
  exports: {
    srv1api: "srv1.api"
  }
}

Now, in the model of projectB1:

// teamB/projectB1/model.c4
model {
  service srv2 {
    -> a2.srv1api
  }
}

We make possible to reference remote projects:

// teamB/projectB1/.likec4rc
{
  name: "projectB1",
  imports: {
    likec4: "github.com/likec4/likec4#v2.0.0",
    az: "dev.azure.com/orgname/project/_git"
  }
}

Here are some other possible applications:

shared specification

We may inherit specifications from another project:

// teamA/projectA1/.likec4rc
{
  name: "projectA1",
  inherits: {
    specification: "../../shared"
  }
}

other configurations

Project configuration can be used to define base "theme", or override current defaults

// teamA/projectA1/.likec4rc
{
  name: "projectA1",

  // extend project config
  extends: "../../base-likec4-config"

  // override styles
  style: {
    color: {
      primary: "#112233"
    }
    size: {
      medium: [200,100]
    }
  }

  // override defaults
  defaults: {
    model: {
      color: "amber",
      opacity: 20,
      size: "small"
    }
    relationship: {
      line: "solid"     
    }
  }
}

[rumpelrausch]

Separation plus optional linking, just like a module system.
Should solve many of the monorepo problems.
I like it!

[mcblair]

Looks promising! A couple thoughts:

• Authentication to private remote projects. Keep life "simple" and rely on user's native git auth and/or credential manager?
• Cyclical relationships. What if Project A imports an element from Project B, and Project B imports an element from Project A that depends on the imported element? Will appropriate aliasing resolve this?
• Aliasing & Conflicts. Will both the exporter and the importer be able to define aliases? Will the tooling inform the user of the conflict (just as it does today)?
• Export Propagation. My gut tells me we don't want Project A to have the ability to export an imported element?
• Versioning. I think requiring a git ref makes the most sense, github.com/likec4/likec4@v1.24.1 or github.com/likec4/likec4@main or github.com/likec4/likec4@SHA. But does it entirely negate the need for a .lock solution? Tags should be immutable, but they can be deleted or recreated. Presumably we'd need an update subcommand and if it had a .lock it would be able to handle these cases.
• Workspace Config File. What about a root level config file in addition to project level config file for those that prefer to manage imports centrally?

Appreciate the hard work 🙏

[davydkov]

Yes @mcblair, good ones 👍🏻

[phlash]

Versioning (again): for remote refs I agree that a git ref should be required, it can be defaulted to HEAD but allow any tree-ish, in the manner of git-checkout so folks can lock to a specific commit, or follow a branch or tag.

Question - when processing remote refs, would LikeC4 clone the repo somewhere? This could be expensive in time/space?

[Cyclonit]

@phlash,ikeC4 must checkout the referenced commit, be it HEAD or anything else. But checking out a single commit without history is cheap and fast.

[jimothyGator]

Having a shared spec (and styles) across multiple projects would be nice. For the time being, I'm using symlinks to simulate this.

My project structure resembles this:

.
├── common
│   ├── spec.c4
│   └── styles.c4
├── projectA
│   ├── common/ -> ../common/
│   ├── common/ -> ../common/
│   ├── likec4.config.json
│   ├── model.c4
│   ├── spec.c4
│   ├── styles.c4
│   └── views.c4
└── projectB
│   ├── common/ -> ../common/
│   ├── common/ -> ../common/
    ├── likec4.config.json
    ├── model.c4
    ├── spec.c4
    ├── styles.c4
    └── views.c4

spec.c4 and styles.c4 under project* define additional specs and styles, and could very well be empty. Notice that common is not a project; it lacks a likec4.config.json file. I argue that common should not define any models, thus there's no reason for it to be a project.

This workaround works well enough, but it would be nice to have official support for it, like @davydkov 's suggestion.

Edit: Rather than symnlink common/spec.c4 and common/styles.c4 individually, I now the common directory. Since LikeC4 recursively scans directories, the two files—plus any additional files created later—are automatically picked up. Tree updated to reflect this.

[StefanStuehrmann]

I know this comment is old but what I use instead is:

_shared/
├── model.c4
└── spec.c4
projectA/
└── likec4.config.json    # include: { paths: ['../_shared'] }
projectB/
└── likec4.config.json    # include: { paths: ['../_shared'] }

Which works nicely and gives you shared model definitions / specs without symlinking.
I took the inspiration from the likec4 test code

likec4/packages/config/src/schema.spec.ts

Line 189 in cd6d44b

include: { paths: ['../shared'] },

Just adding a comment because project observers might be stumble over how to do.

[ptumilovich]

Also it would be nice to have an option to give a title to project. For example it can be used in "projects" page as a title for project button. Currently you can specify only "name" in config which is more like an id than actual name

[almereyda]

• Set title per project and for development (serve) #2093

is related here.

[a-scolan]

This is a must and would be a killer feature, allowing to use LikeC4 at scales above a few separate app domains

[a-scolan]

Just made a financial contribution to LikeC4 on OpenCollective, as I would really love this feature to come out sooner rather than later.
I am also trying to see how I could contribute to the code, though I am no expert on this type of codebases.

[davydkov]

Hey @a-scolan

Thank you for support!
Can you reach me on Discord?

[Yash-xoxo]

This would be really useful for monorepos. A few thoughts:

Config structure looks solid. The nested projects array makes sense and should scale well.

Suggestion: Add a root or defaultProject field so tools know which project to use when no context is available:

{
  "defaultProject": "api",
  "projects": [
    {
      "name": "api",
      "path": "./packages/api"
    },
    {
      "name": "web",
      "path": "./packages/web"
    }
  ]
}

For tooling integration: How would this work with commands? Something like:

# Run command in specific project
npm run build --project=api

# Or run across all projects
npm run test --all-projects

Workspace compatibility: Would this play nicely with npm/yarn/pnpm workspaces, or replace that concept?

Happy to test this out if there's a prototype!

[Yash-xoxo]

This would be really useful for monorepos. A few thoughts:

Config structure looks solid. The nested projects array makes sense and should scale well.

Suggestion: Add a root or defaultProject field so tools know which project to use when no context is available:

{
  "defaultProject": "api",
  "projects": [
    {
      "name": "api",
      "path": "./packages/api"
    },
    {
      "name": "web",
      "path": "./packages/web"
    }
  ]
}

For tooling integration: How would this work with commands? Something like:

# Run command in specific project
npm run build --project=api

# Or run across all projects
npm run test --all-projects

Workspace compatibility: Would this play nicely with npm/yarn/pnpm workspaces, or replace that concept?

Happy to test this out if there's a prototype!