Projects¶

Part of the user manual. Related: VISIBILITY · TENANCY · PERMISSIONS · ROLES · NOTIFICATIONS · WORKFLOWS · CONTACTS. Project membership is layer 2 and data sources are layer 3 of the five visibility layers.

Projects are the top-level organisational unit in REBIM. Most things in the system — documents, workflow events, transmittals, scheduled events, people assignments — belong to a project. Tenancy (TENANCY) decides which projects exist in your world; project membership decides which of those you can actually enter.

This page covers what a project is, who can see it, what hangs off it, and how to manage one in practice.

TL;DR¶

A project is the container for documents, workflow events, transmittals, scheduled events, and project people. Most user activity happens inside a project.
Project membership (visibility layer 2): tenancy alone doesn't grant project access. A user must be the project's owner OR have a ProjectPeople row linking their contact to the project.
Data sources (visibility layer 3): documents inside a project are bucketed by data source. Each data source carries its own tenancy. Same project, different users, different document subsets.
A project has its own taxonomies — systems, levels, spaces — which classify documents and gate compliance counts.
Each project can override the system email sender + template (email_from, email_template) so notifications carry a project-specific identity.

What a project is¶

A project is one row in apps.projects.Project. It carries:

Attribute	Type	Purpose
`name`	string	Display name
`reference`	string	Short identifier, e.g. project code
`project_type`	choice	BIM / HSE / FSS / COM / ECP / HEN — classification (drives filter views)
`description`	text	Long-form description
`site_owner`, `site_responsibility`	text	Free-text fields surfaced on dashboards (compliance + reports)
`image`	image	Logo / cover image shown in project lists
`default_model_pk`	int	Default 3D model document to open in the launcher
`email_from`	email	Override the system default sender for emails about this project
`email_template`	FK	Override the default email template — project-branded styling
`single_exclusive_workflow`	FK to WorkflowWorkflow	Constrains the project to a single workflow definition (only used when that workflow has `only_show_if_exclusive=True`)
`pinned`	bool	Sticky in the user's project list
`is_active`	bool	False = soft-archived (hidden from default lists, see Archive vs delete)
`complete`	bool	Marked complete (separate from is_active — see Mark complete)
`tenants`	M2M	Tenancy (TENANCY)
`owner`	FK to User	Creator

It also owns three many-to-many taxonomies — see Per-project taxonomies below.

Project membership (visibility layer 2)¶

Tenancy alone doesn't grant project access. A user sees a project only if at least one of:

The user is the project's owner (creator), OR
A ProjectPeople row exists linking the user's contact to the project, OR
The user is a superuser.

This is enforced backend-side by apps.projects.models.ProjectManager.for_user and frontend-side by the project list filter.

ProjectPeople — the membership row¶

ProjectPeople is the join row between a Contact and a Project. It also carries:

disciplines (M2M to ProjectDiscipline) — the user's role(s) on this project. Gates workflow event visibility — see ROLES.
project_admin (bool) — full admin rights within this project. See Project admin.
role_leader (bool) — broader role-side visibility + unlocks requires_role_leader transitions. See ROLES.
owner (FK to User) — DataModel field. The user who created the ProjectPeople row (not the project person themselves).
tenants (M2M) — tenancy applies here too.

Owner vs project_admin vs role_leader¶

These three flags often get conflated. They're independent:

Flag	Scope	Effect
Project owner	The user who created the project	Permanent owner — sees the project, can edit / delete it (subject to group perms)
`project_admin`	Per ProjectPeople row	Within this project: full visibility, full action rights, manages other ProjectPeople. Per-project equivalent of superuser.
`role_leader`	Per ProjectPeople row	Within this project, for the user's assigned disciplines: broader role-side workflow visibility + unlocks `requires_role_leader` transitions. See ROLES.

A user can hold any combination. Common patterns:

Project manager: not the owner, project_admin=True, no specific disciplines needed.
Lead Architect: not project_admin, disciplines=[Architect], role_leader=True.
Junior Architect: not project_admin, disciplines=[Architect], role_leader=False.
The project creator who's also running it: owner + project_admin on their own ProjectPeople row.

Adding / removing project membership¶

Open the project → People tab → "Add Person" / kebab to edit / remove. Requires the user doing it to be the project's owner OR a project admin OR a superuser. Adding requires the contact to already exist (see CONTACTS, planned). See PERMISSIONS § Project People for the full edit gate.

Data sources (visibility layer 3)¶

Within a project, documents live in data sources. A data source is a logical bucket for documents — typically used to scope documents by source-of-truth (e.g. local upload vs SharePoint sync) or by contributing party (one data source per consultant / contractor / trade).

Each Project.data_sources is many-to-many — a project can have multiple data sources, and one data source can in principle be shared across projects (though that's uncommon in practice).

Data source attributes¶

Attribute	Purpose
`name`	Display name
`data_source`	Enum: `Local` (uploaded into REBIM) or `Sharepoint` (mirrored from a SharePoint site)
`settings`	Per-source configuration (e.g. SharePoint URL + auth)
`pause_sync`	Pause automatic SharePoint sync without removing the source
`documents_match_tenancy`	When True (default), documents created via the bulk uploader and single-document create inherit the data source's tenancy. When False, they inherit the uploading user's tenancy instead.
`tenants`	M2M — the data source's own tenancy

How data sources gate visibility¶

A user sees a document only if:

The document's data source belongs to a project the user can see (layer 2: project membership), AND
The data source's tenants intersect the user's tenants (this layer).

The second part is what makes data sources useful for project-scoped-but-party-partitioned setups. Example:

Project "Phase 3 Renovation" has three data sources:
Phase 3 Main (tenants: EUS-O, AZL-O)
Phase 3 MEP Subcontractor (tenants: EUS-O, MEP-O)
Phase 3 Architect (tenants: EUS-O, ARC-O)
Internal staff (EUS-O): see all three data sources, see all documents in the project.
MEP subcontractor (EUS-O, MEP-O): see Phase 3 Main + Phase 3 MEP Subcontractor sources, but NOT the Architect source.
Architect (EUS-O, ARC-O): see Phase 3 Main + Phase 3 Architect sources, but NOT the MEP one.

All three groups appear to be in the same project (because Phase 3 Main is visible to everyone via the shared EUS-O config tenant) but the document subsets they see are partitioned cleanly.

`documents_match_tenancy`¶

When this is True (the default), documents created through the bulk uploader and single-document create inherit the data source's tenancy regardless of the uploader. This is the safe default — it keeps documents in the data source's intended scope even if a multi-tenancy user uploads them. If the data source itself has no tenancy set, both paths fall back to the uploader's tenancy (never untenanted, which would otherwise be invisible to tenanted users).

Setting it to False causes new documents (bulk or single) to inherit the uploader's tenancy instead. Use only when you genuinely want per-uploader scoping within a single data source — unusual.

Symptom: user can see project but no / few documents¶

Almost always a data source mismatch — the project's data sources don't all carry tenancy the user has. Check data_source.tenants for each source on the project vs the user's tenancy. See VISIBILITY for the troubleshooting flow.

Per-project taxonomies¶

Projects own three many-to-many taxonomies for classifying documents:

Systems (`ProjectSystem`)¶

Building or asset systems — e.g. HVAC, Electrical, Plumbing, Structural, Fire Safety. Each system has:

code (e.g. HVAC) + name (e.g. HVAC system)
area (optional grouping)
is_primary (bool) — primary systems are surfaced in compliance counts on the dashboard. Non-primary systems still exist but don't affect those rollups.
workflow_start_to_due_days — when a workflow is created against a document in this system, default the event due date to N days out from start. Per-system tuning of workflow timing.

Systems are assigned to documents via EdmsDocument.system (single-value FK, despite the project's M2M list).

Levels (`ProjectLevel`)¶

Building floors / strata — e.g. Ground, L1, L2, Mezzanine, Roof. Simple classification, no per-level behaviour beyond filtering.

Assigned to documents via EdmsDocument.level (FK).

Spaces (`ProjectSpace`)¶

Rooms / zones within a level (when the ENABLE_EDMS_SPACES setting is True). Optional extra classification layer.

Assigned to documents via EdmsDocument.space (FK).

Disciplines (roles) — not a taxonomy here¶

Disciplines are tenancy-wide (not per-project) and are covered in ROLES. Mentioned here for completeness — they're attached to project members via ProjectPeople.disciplines, not directly to the project.

Project lifecycle¶

Create¶

Requires add_project group permission (typically the PROJECTS CRUD group — see PERMISSIONS).

The creator becomes the project's owner. The creator does NOT get an automatic ProjectPeople row — they see the project via the owner path, but to also participate as a project person (with disciplines, role_leader status, etc.) they need to add themselves to the People tab.

On creation, the project is empty of data sources, taxonomies, and people. All of those are added afterwards.

Edit¶

Requires change_project group permission AND the user is the project's owner OR a project admin. See PERMISSIONS § Projects.

Most attributes can be changed freely after creation. Two with extra care:

tenants — changing tenancy mid-project may make the project invisible to existing members. See TENANCY § Reorganising tenancy without surprises.
single_exclusive_workflow — only effective when paired with a workflow definition that has only_show_if_exclusive=True. Changing this can hide existing events whose workflow doesn't match.

Archive (is_active = False)¶

Setting is_active=False soft-archives the project. The project:

Hides from default project lists (filtered out unless a user explicitly views archived projects).
Remains in the database — data is preserved.
Workflows + notifications continue to fire (archive is a UX filter, not a behaviour disable).
Can be un-archived by flipping is_active=True.

Use for completed / paused projects that should drop out of the day-to-day view without being deleted.

Mark complete¶

complete=True is a separate flag from is_active. It marks the project as having reached completion (formal sign-off), and:

Surfaces on the project list with a "complete" indicator.
Affects compliance reports — completed projects count differently in some dashboards.
Does NOT hide the project (use is_active=False for that).

Treat the two flags as orthogonal:

Active	Complete	Meaning
✓	✗	Live project, in progress
✓	✓	Live project, formally complete (rare — see use case)
✗	✗	Archived, was abandoned mid-project
✗	✓	Archived, completed normally (most common archived state)

Delete¶

Rare. Requires delete_project group permission AND owner / project admin / superuser. Cascades to:

All ProjectPeople rows for the project.
All workflow events tied to the project.
All transmittals tied to the project.
Schedule events tied to the project.

Does NOT cascade to:

Documents (they belong to data sources, which can survive the project being deleted if the data source is referenced elsewhere — rare).
Contacts (org-wide, not project-scoped).

For most "shut this project down" cases, prefer is_active=False over delete. Delete only when the project was created in error or is genuinely never coming back AND its data isn't needed.

The project tabs¶

Each project shows a set of tabs when opened. Their availability depends on the project's configuration and the user's role:

Workflows — the main workflow event table. BYOP-chunked, filtered by role visibility (see ROLES). Default tab.
Transmittals — the transmittals table, with bake history and CSV export. See TRANSMITTALS.
Documents (EDMS) — the document table. May have a second sub-tab for Compliance documents if any exist (the sub-tab's name is configurable via SECOND_EDMS_TAB in settings — default "Compliance", some installs rename to e.g. "Capital Works").
People — the project member list. Where ProjectPeople rows are managed. See PEOPLE for the tab's column list + intent-routed "what do you want to do?" map.
Scheduler — scheduled events (recurring workflow triggers, due reminders). Visible to all project members; create / edit requires project admin + SCHEDULE CRUD group. See SCHEDULER.
Contacts — the project's contact list. See CONTACTS for the full Contacts tab story.
Explorer — not a data tab. The side-menu toggle only shows/hides the Explorer panel, which is a document tool (EXPLORER) — empty until you launch it on a specific document or model. It inspects that document's events + 3D elements, not the project as a whole.

The exact tab set depends on install configuration and the user's group permissions. Tabs the user has no view permission for are hidden entirely.

Practical operations¶

Create a project¶

Dashboard → projects list → "Add Project" (visible if you have add_project).
Fill the form: name, reference, project_type, description, etc.
Set initial tenants — usually the config tenant + relevant data tenant(s). See TENANCY.
Save. You're now the owner.
Open the project → set up data sources (next), then people, then taxonomies as needed.

Add a data source to a project¶

Project → settings / data sources area.
"Add Data Source" — either select an existing one or create inline.
Set its tenancy. Decide documents_match_tenancy (default True is usually right).
Save.

The data source is now available for documents within the project.

Add a project member¶

See Adding / removing project membership above. The full flow is in ROLES § Practical operations since most of the interesting fields are role-related.

Hand over project ownership¶

REBIM doesn't have a built-in "transfer ownership" action. The practical approach:

Promote the new owner to project_admin via their ProjectPeople row.
They now have full project rights without needing actual ownership.

Actual ownership changes — moving Project.owner — require admin panel access (superuser only). Avoid unless the original owner has genuinely left the org and historical-record cleanliness matters.

Archive vs delete¶

Archive (is_active=False) for almost all "we're done with this project" cases. Delete only when the project was created in error.

Troubleshooting¶

Symptom	Likely cause	First check
User added to tenancy can't see any projects	No `ProjectPeople` rows, owns no projects (layer 2)	Add their contact to the relevant projects
Can see project but no documents	Data source tenancy mismatch (layer 3)	`data_source.tenants` per source on the project
Can see SOME documents but expected more	Same as above — one data source on the project doesn't match the user's tenancy	Same
New data source's documents invisible after upload	`documents_match_tenancy=False` AND the uploader had no matching tenancy	Toggle to True (default) and re-upload, or set tenancy on the uploaded docs
Project member can't manage other members	Missing `project_admin` on their ProjectPeople row (or not the owner)	Promote them to project admin
Project shows in admin but not in user's project list	User isn't owner or member of this project	Add them as a project person, or grant ownership
Just archived a project, users say workflows still fire emails	Archive (`is_active=False`) doesn't disable workflow behaviour — just hides from default lists	Either accept (the project's still "alive"), or also mark events complete / disable specific workflows
Project has tenants set but user with overlapping tenancy can't see it	Tenancy overlap is necessary but not sufficient — need project membership too (layer 2)	`ProjectPeople` rows

For developers¶

This page is for users and admins. Implementation pointers:

Models:
apps.projects.models.Project — the project itself.
apps.projects.models.ProjectPeople — membership row.
apps.projects.models.ProjectDiscipline / ProjectSystem / ProjectLevel / ProjectSpace — per-project taxonomies (note: Disciplines are tenancy-wide, the others are too — but they're attached to projects via M2M).
apps.edms.models.EdmsDataSource — data sources.
Access filter: apps.projects.models.ProjectManager.for_user — encapsulates "user can see project" (tenancy + membership). Both the ProjectViewSet and any function-based endpoint that needs project access checking go through this.
Data source filter: applied per-document in EDMS viewsets + the dir @action on Project + the BYOP edms_project_documents endpoint.

See devdocs/ for codebase-level material.