Collaborating on a Project

In this tutorial, you’ll add organisation members to a project, assign project-level roles, and see how real-time collaboration works when multiple people are modelling together.

Prerequisites: You’ve completed Inviting Members and have at least one other member in your organisation. You’ve completed Working with Projects.

1. The Two-Level Access Model

Farkitect uses two levels of access control:

Organisation membership — controls who can see the organisation and its projects at all
Project roles — controls what a member can do within a specific project

A person must be an organisation member before they can be added to any project. Once added to a project, their project role determines their permissions.

2. Project Roles

Role	What they can do
Admin	Full control — edit models, manage diagrams, manage project members, delete project
Contributor	Edit models, create and edit diagrams, manage catalogs. Cannot manage project membership.
Viewer	Read-only access — view diagrams, explore the model, view properties. Cannot edit anything.

3. Add Members to a Project

Open the project you want to share
Navigate to the project settings or member management area
Click Add Member
Select from your organisation’s members (only people already in the organisation appear)
Assign a project role: Admin, Contributor, or Viewer
Confirm

The member now has access to this project at their assigned role level. They’ll see the project in their project switcher.

4. Real-Time Collaboration

When multiple people are working in the same project, changes appear in real time:

Element creation — when someone creates an element, it appears in your Explorer within moments
Property edits — when someone changes a property value, you see it update in the Properties panel and in catalogs
Relationship changes — new or deleted relationships are reflected across all views
Diagram layout — diagram node positions and edge routes are per-diagram-save, so you won’t see another user’s unsaved layout changes until they save

This real-time sync is powered by Convex’s reactive backend — there’s no “refresh” button. The model is always current.

What’s not real-time

Diagram layout is saved explicitly (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 is per-user, per-project. Your panel arrangement doesn’t affect anyone else.

5. Role-Aware UI

The interface adapts based on your project role:

Viewers see a read-only interface — editing controls are hidden or disabled. They can explore the model, open diagrams, and view properties, but can’t change anything.
Contributors see the full editing interface but can’t manage project membership.
Admins see everything including member management.

This means you don’t need to worry about viewers accidentally changing things — the UI prevents it.

6. Managing Project Members

As a project Admin:

Navigate to the project’s member management area
You can:
- Change a member’s role — promote a Viewer to Contributor, or a Contributor to Admin
- Remove a member — revoke their access to this project (they remain in the organisation)

Removing someone from a project doesn’t remove them from the organisation. They can still access other projects they’re members of.

What You’ve Learned

The two-level access model: organisation membership + project roles
The three project roles (Admin, Contributor, Viewer) and what each can do
How to add organisation members to a project with a specific role
How real-time collaboration works — model changes sync instantly, diagram layout syncs on save
How the UI adapts based on the user’s role
How to manage project members (change roles, remove)

Next Steps

You’ve now completed the full tutorial track. From here:

How-to Guides — Task-specific directions for specific goals
Explanation — Deeper reading on concepts and design decisions
Reference — Technical specifications to consult while working