Skip to Content
DocumentationProject Workspace

Project Workspace

Project Workspace groups architecture design documents and diagrams in one place.

Project Workspace supports two storage modes:

  • Cloud canonical: DiagramFlow Cloud stores project metadata, Markdown design documents, project access state, project context, Cloud document revisions, and export jobs.
  • Git canonical: your GitHub repository stores the canonical Markdown, .df, and manifest files; DiagramFlow Cloud stores repo mappings, project access state, project context, sync jobs, and short-lived read/cache state.

Use Project Workspace when a design needs more than one standalone diagram: architecture notes, C4 views, service diagrams, and exportable documentation can live together under the same project.

What a project stores

A project can include:

  • Design documents written in Markdown
  • DiagramFlow .df diagrams tracked by the project or referenced from Markdown
  • Inline Markdown diagramflow references from documents to diagrams
  • Project-level sharing and public-view configuration
  • Project context metadata used by authenticated and public workspace views
  • Cloud document revisions for Markdown changes
  • Export jobs for downloadable project archives

Choose Cloud canonical when you want fast in-app authoring, in-app revision history, and ZIP export. Choose Git canonical when your team wants the repository to remain the source of truth and DiagramFlow saves should become commits.

Access model

Project Workspace access is managed at the project level.

  • Owners can keep the workspace private, invite verified email addresses as view or contribute, or enable a public read-only link.
  • Documents inherit access from the project. DiagramFlow does not create document-level ACLs for Project Workspace.
  • Copying a document link creates a deep link into the same project access boundary. It does not create a new share.
  • Public links are view-only. They expose only the project, document, and context fields marked safe for anonymous access.
  • Private projects remain unavailable on public /projects/:projectId routes, even when the current signed-in user could access the same workspace through dashboard routes.

Public links are intentional publication.

  • Anyone with the public link can read the public Project Workspace viewer.
  • Public routes return the same unavailable treatment for private, missing, deleted, or unpublished projects so they do not reveal private-project metadata.
  • Public viewers do not receive collaborator emails, private grants, revision history, owner-only controls, drafts, or inaccessible diagram source or image data.
  • Public project access does not grant transitive access to private diagrams referenced inside a document.

Design documents

Design documents are Markdown-first. Write the architecture narrative in Markdown, then reference any diagram the current editor can access directly inside the Markdown body.

When you save a Cloud document, DiagramFlow checks the current revision. If someone has saved a newer revision first, DiagramFlow reports a conflict instead of overwriting their work. Reload the latest revision, merge your changes, and save again.

Use the fenced diagramflow block syntax to reference a diagram:

```diagramflow {diagram-123}
```

Markdown stays canonical across Cloud, Git, public viewing, and export flows.

Diagram blocks and diagram access

diagramflow fenced blocks are the source of truth for document-level diagram references.

  • A document can reference any diagram the current editor is allowed to view. The diagram does not need to be attached to the same project first.
  • Referencing a diagram inside a document does not grant transitive access to that diagram for other viewers.
  • Authenticated and public viewers both resolve diagram access at view time.
  • Allowed diagrams render normally.
  • Denied diagrams render the explicit placeholder You do not have access to this diagram.
  • Missing or malformed references render a safe fallback without leaking diagram metadata.

Git canonical workflow

Git canonical mode is GitHub-first.

  1. Connect the DiagramFlow GitHub App.
  2. Import a repository, branch, and optional base path into a project workspace.
  3. DiagramFlow reads .diagramflow/manifest.json plus the referenced Markdown and .df files.
  4. Saving a repo-backed document or .df file creates a commit when the branch head still matches the editor’s base_commit_sha.
  5. If the branch moved, DiagramFlow stops the save and asks you to resolve the conflict instead of overwriting remote content.

DiagramFlow does not store canonical Markdown or .df code for Git canonical projects in PostgreSQL. The database stores repo mapping metadata, project access state, tracked file paths, last known commit SHA, and Git sync job state only.

Invited contributors can edit Git-backed projects through DiagramFlow Project Workspace permissions, while repository writes still use the project owner’s connected Git provider credential as the storage credential.

  • DiagramFlow project permission controls who can edit through the product.
  • DiagramFlow preserves the acting user in product audit context.
  • DiagramFlow does not require project-shared contributors to already have direct GitHub collaborator access to the repository.
  • DiagramFlow does not imply that it is checking GitHub collaborator membership as part of Project Workspace sharing. GitHub acts as the storage boundary, while DiagramFlow project permission acts as the product-access boundary.

Revision history

Cloud canonical projects expose DiagramFlow revision history for Markdown documents, including list, preview, and restore-by-new-head flows.

Git canonical projects do not expose DiagramFlow-managed document revisions. Git-backed views show repository source, sync, conflict, and commit context instead.

Export layout

A project ZIP export uses this structure:

docs/
  overview.md
diagrams/
  order-flow.df
.diagramflow/
  manifest.json

The docs/ folder contains Markdown design documents. The diagrams/ folder contains .df source files. The .diagramflow/manifest.json file maps stable DiagramFlow document and diagram IDs to exported paths.

Example manifest shape:

{
  "format_version": 1,
  "project_id": "project-123",
  "documents": [
    {
      "id": "document-456",
      "slug": "overview",
      "path": "docs/overview.md"
    }
  ],
  "diagrams": [
    {
      "id": "diagram-789",
      "name": "Order Flow",
      "source_path": "diagrams/order-flow.df"
    }
  ]
}

Example Markdown diagram reference:

```diagramflow {diagram-789}

Markdown export preserves `diagramflow` fenced blocks in this release. DiagramFlow does not replace them with rendered diagram image files during Project Workspace export.

In Git canonical mode, the repository keeps `docs/*.md`, `diagrams/*.df`, and `.diagramflow/manifest.json` canonical.

## Source of truth

For Cloud canonical projects:

- Edit and save documents in DiagramFlow.
- Edit diagrams in the DiagramFlow dashboard editor.
- Use export when you need portable Markdown, `.df`, and manifest files.
- Do not expect repository changes to automatically update the project.

For Git canonical projects:

- Connect GitHub once through the DiagramFlow GitHub App.
- Import a manifest-backed repo folder into a project.
- Save Markdown and `.df` changes as repository commits.
- Resolve branch movement explicitly when DiagramFlow detects a conflicting remote change.

This keeps each mode predictable: Cloud canonical optimizes for in-app authoring, while Git canonical keeps the repository authoritative.

## Related docs

- [What is DiagramFlow?](/docs/what-is-diagramflow)
- [Quickstart](/docs/quickstart)
- [What is Diagram as Code?](/docs/what-is-diagram-as-code)
- [Diagram Configs](/docs/diagram-configs)
Last updated on
QuickstartWhat is Diagram as Code?