Skip to content
Farkitect
🤷

Forgive us! These docs are a work in progress. Some pages may be incomplete or describe features that aren't quite finished yet. Farkitect is in early development and we don't recommend using it for real work just yet. Feel free to explore — just be aware that things are still being built.

Organisations, Projects, and Collaboration

Farkitect’s collaboration model has two levels: organisations and projects. Understanding how they relate — and why both exist — is key to setting up your team effectively.

The Two Levels

Section titled “The Two Levels”

Organisation

Section titled “Organisation”

An organisation is the people boundary. It represents your company, team, or working group — the set of people who might need to collaborate on models.

An organisation contains:

  • Members — people with accounts who have been invited to the organisation
  • Projects — the modelling workspaces where work happens
  • Settings — configuration that applies organisation-wide (jurisdiction, notification thresholds)

Project

Section titled “Project”

A project is the data boundary. It’s an isolated modelling workspace containing packages, elements, relationships, diagrams, and catalogs.

A project contains:

  • Packages — the M3, M2, and M1 package trees that make up the model
  • Members — the subset of organisation members who have access to this project, each with a role

Why Two Levels?

Section titled “Why Two Levels?”

Because not everyone in an organisation should see every project.

In a consulting firm, the organisation is the firm. Each client engagement is a project. Consultants are invited to the organisation once, then added to specific client projects as needed. A consultant working on the Farquind engagement shouldn’t accidentally see the data model for a different client.

In a product company, the organisation is the company. Different teams might have separate projects — one for the application architecture, one for the data model, one for business process mapping. Team members are added to the projects they work on.

The two-level model provides:

  • Simple onboarding — invite to the organisation once; add to projects as needed
  • Data isolation — project data is visible only to project members
  • Flexible access — different people can have different roles on different projects

Organisation Membership as Gateway

Section titled “Organisation Membership as Gateway”

A person must be an organisation member before they can be added to any project within that organisation. This is the gateway:

  1. Someone invites you to the organisation (via email invitation)
  2. You accept and become a member
  3. An admin adds you to specific projects with a project-level role

You cannot skip step 1. There’s no way to access a project without being a member of its parent organisation first.

Real-Time Sync

Section titled “Real-Time Sync”

When multiple people are working in the same project, changes propagate in real time via Convex’s reactive backend:

  • Element creation and deletion — appears in the Explorer within moments
  • Property value changes — update in the Properties panel and catalogs immediately
  • Relationship changes — reflected across all views
  • Model structure changes — new packages, moved elements, renamed items sync instantly

What’s not real-time

Section titled “What’s not real-time”

Diagram layout (node positions, edge waypoints, formatting overrides) is saved explicitly with Ctrl+S. Two people editing the same diagram simultaneously will overwrite each other’s layout on save. For now, coordinate diagram editing — one person at a time per diagram.

Panel layout (which panels are open, their positions) is per-user and per-project. Your workspace arrangement doesn’t affect anyone else.

Optimistic Updates

Section titled “Optimistic Updates”

When you create an element or change a property, the change appears in your UI immediately — before the server confirms it. This is called an optimistic update. If the server rejects the change (for example, due to a permissions issue), the UI rolls back.

In practice, you’ll rarely notice this. Changes feel instant. The technical mechanism (optimistic update with server confirmation) is invisible unless something goes wrong.

Data Isolation

Section titled “Data Isolation”

Project-level data isolation means:

  • Elements in Project A are not visible in Project B
  • Searching, filtering, and cataloging only see the current project’s data
  • Exporting from a project captures only that project’s content
  • Deleting a project removes all its data (with an automatic .farki export for safety)

System packages (M3 MOF Core, M2 Common, built-in M2 metamodels) are shared across all projects — they’re the same read-only packages everywhere.