Projects

Projects are mid-level organizational containers within spaces that hold multiple task lists. They provide structure for organizing related work, tracking progress, and managing team collaboration between the high-level space organization and detailed list work.

Understanding Projects

Organizational Hierarchy

Workspace
└── Space (Top level organization)
    └── Project (Mid-level organization)
        └── List (Task container)
            └── Task

Projects contain:

Multiple task lists organized by project scope
Project members with role-based access
Project manager for oversight and ownership
Project-specific settings and configuration
Dashboard analytics with performance metrics
Start and target dates for timeline tracking
Status and priority indicators

Example projects:

“Mosaic Features” - Feature development
“Mosaic Phase 1” - Project phase implementation
“Mosaic Phase 2 (plans and subscriptions)” - Specific feature phase

Accessing Projects

Projects Overview Page

Navigate to Projects from:

Main navigation: Click “Projects” in the main menu
Sidebar: Projects section (shows total count)
Within spaces: Navigate to a space and view Projects tab

From Spaces

Navigation path:

Open a Space detail page
Projects tab (default view) shows all projects in that space
Click any project card to open project detail view

Direct access:

Projects section in sidebar displays total project count
Click any project name for direct access
Expand spaces to see their projects in hierarchical view
Projects show their list count (e.g., “5 lists”, “51 lists”)

Project Detail View

Click any project to access the comprehensive detail page with multiple tabs for different project management aspects.

Project Header

Elements visible:

Project icon/emoji - Visual identifier for the project
Project name - Title displayed prominently
Lists counter badge - Shows list count (e.g., “5 lists”) in blue pill
Member avatars - Project members displayed with SelectMembers dropdown
Status dropdown - Project status selection (Backlog, ToDo, In Progress, In Review, On Hold, Blocked, Completed, Cancelled)
Priority dropdown - Priority selection (Low, Normal, High, Urgent, Critical, Blocker)
Privacy indicator - Lock icon if project is private

Available Tabs

The project detail page includes five tabs accessible from the tab navigation:

1. Task Lists Tab (Default)

View and manage all lists within the project. This is the default tab when opening a project.

Board View:

Task lists displayed as kanban cards
Visual overview of all lists in the project
Status-based column organization
Quick navigation to individual lists
“Add New List” option available

List View:

Comprehensive list information in table format
All task lists visible with detailed metadata
List title, status, priority, and members shown
Better for managing many lists efficiently
Search and filter capabilities

2. Tasks Tab

View and manage all tasks across all lists in the project, providing a cross-list overview of all work items.

Board View:

All project tasks regardless of which list they belong to
Status-based kanban columns (Backlog, ToDo, In Progress, etc.)
Drag and drop to update task status
Quick overview of entire project workload
Search and filter capabilities

Benefits:

See all project work at once without navigating between lists
Understand project status holistically across all lists
Manage tasks across multiple lists from single view
Identify bottlenecks and workload distribution
Cross-list task coordination

3. Dashboard Tab

Project analytics, metrics, and performance insights.

Features:

Project performance metrics and KPIs
Task completion rates and progress tracking
Progress visualization with charts and graphs
Team activity tracking and member performance
Timeline information and milestone tracking
Completion rates and velocity metrics
Bottleneck identification

The dashboard provides comprehensive project health insights for informed decision-making.

4. Info Tab

View and edit project information and metadata.

Information displayed:

Start Date - Project start date (editable with date picker)
Target Date - Project deadline/target completion (editable with date picker)
Description - Rich text editor for detailed project description
- Supports formatted text, lists, links
- Inline editing with bubble menu
- Floating menu for formatting options
- Updates on blur if not empty

Date validation:

Start date cannot be after target date
Target date cannot be before start date
System validates date logic and displays error toasts

5. Settings Tab

Configure all project properties, access control, and danger zone operations.

General Settings:

Project Icon - Icon/emoji picker with color selection
Project Title - Edit project name (updates on blur)
Project Visibility - “Make project private” checkbox for access control

Project Manager:

Assign a team member as project manager
Manager must be one of the project members
Only one manager per project
Manager has oversight and ownership responsibilities

Project Members:

Add and remove project members
Assign member roles (Admin, User)
View current member list with roles
Control who has access to the project
Member management requires Update permission

Danger Zone:

Delete Project - Permanently remove the project
Requires Delete permission
Deletes project and all its data
Requires typing exact project title to confirm
Redirects to Tasks page after deletion
This action cannot be undone

Creating and Managing Projects

Creating a Project

Creation process:

Navigate to a Space detail page
Go to Projects tab (default view)
Click ”+” or “Create Project” button (if available)
Fill in project details in the creation modal:
- Project Title (required) - Enter a descriptive name
- Icon/Emoji (optional) - Select visual identifier
- Color (optional) - Choose project color theme
- Description (optional) - Add project description
- Space (required) - Assign to current space (auto-filled)
- Manager (optional) - Designate project manager
- Members (optional) - Add initial team members
- Privacy (optional) - Set “Make project private” if needed
Click “Create Project” to save

Quick create from sidebar:

”+ Add Project” button visible in expanded spaces
Creates project in the context of that space

Project fields:

Title: Project display name (required)
Space: Parent space (required, auto-assigned)
Workspace: Parent workspace (auto-fetched from space)
Status: Project status (default: Backlog)
Priority: Project priority (default: Normal)
Icon: Emoji or icon for identification
Color: Color theme for visual distinction
Description: Rich text description of project purpose
Start Date: Project start date
Target Date: Project target completion date
Manager: Designated project manager
Members: List of project team members with roles
Is Private: Privacy flag for access control
Is Archived: Archive status
Is Billable: Billable project indicator
Done: Completion flag
Created By: User who created the project (auto-set)

Editing a Project

To modify project properties:

Open the project detail page
Navigate to Settings tab for configuration changes
Or navigate to Info tab for dates and description
Update desired properties:
- Settings tab: Title, icon, color, visibility, manager, members
- Info tab: Start date, target date, description
Changes save automatically on blur or selection

Permission requirements:

Update permission required to edit project properties
Update permission required to manage members
Delete permission required to delete project

Editable elements:

Project title - Change name (Settings tab)
Project icon and color - Update visual identity (Settings tab)
Description - Edit rich text description (Info tab)
Start and target dates - Set project timeline (Info tab)
Visibility - Toggle private/public (Settings tab)
Manager - Assign project manager (Settings tab)
Members and roles - Manage team access (Settings tab)
Status - Update from header dropdown (requires Update permission)
Priority - Change from header dropdown (requires Update permission)

Managing Lists

Within a project:

View all lists in Task Lists tab (default tab)
Switch between Board view (kanban) and List view (table)
Create new lists using “Add New List” option
Search and filter lists by criteria
Organize lists by status in board view
Click any list to open list detail page

List management permissions:

Create permission on MTask List DocType required to add lists
Lists are automatically assigned to the current project
Lists can be moved between projects via list settings

For comprehensive list management details, see Lists.

Archiving Projects

Archive functionality:

Projects can be archived using the is_archived flag
Archived projects are hidden from normal views
Archived projects can be retrieved via API endpoint
Use archiving to preserve project history without deletion

To view archived projects:

API endpoint: get_archived_projects(space: str) returns archived projects for a space

Project Progress Tracking

Progress Indicators

Lists counter badge:

Displayed in project header as blue pill
Shows total list count (e.g., “5 lists”, “51 lists”)
Click to view Task Lists tab
Provides quick overview of project scope

Dashboard metrics:

Access comprehensive analytics via Dashboard tab
Track completion rates and progress trends
Monitor team performance and velocity
Identify bottlenecks and delays

Dashboard Analytics

Available analytics:

Task completion rates - Percentage of completed tasks
Timeline progress - Progress against start and target dates
Team activity - Member contributions and performance
Bottleneck identification - Identify blocked or delayed work
Performance insights - KPIs and metrics for project health
Velocity tracking - Team productivity over time
Milestone tracking - Progress toward key milestones

The dashboard provides data-driven insights for project management decisions.

Project Hierarchy

Projects appear in the sidebar hierarchy showing the organizational structure:

Workspace: Current Workspace
└── Space: "Mosic Platform"
    ├── Project: "Mosaic Features" (5 lists)
    │   ├── List: "Mosaic Backlog Features" (28 items)
    │   ├── List: "Mosaic Quick Fixes" (1 item)
    │   ├── List: Additional lists...
    │   └── "+ Add Task List" button
    └── Project: "Mosaic Phase 3" (51 lists)
        ├── List: Various lists
        └── "+ Add Task List" button

Sidebar features:

Expandable/collapsible spaces and projects
List counts displayed next to project names (e.g., “5 lists”, “51 lists”)
Task counts shown for individual lists (e.g., “28 items”, “1 item”)
Quick navigation to any level with single click
”+ Add Task List” button for quick list creation in context
”+ Add Project” button for quick project creation within space
Visual hierarchy with indentation showing relationships

Project Views

Within Space Detail

Projects are displayed in the Space detail page’s Projects tab (the default tab when opening a space).

Board View (Kanban):

Projects displayed as kanban cards
Visual card-based organization
Each card shows project icon, title, members, and metadata
Quick project access with card click
Status indicators and badges
Better for visual overview of fewer projects

List View (Table):

Detailed project information in table format
Multiple projects visible in scrollable list
More metadata shown per project (title, status, priority, manager, dates)
Comprehensive project details at a glance
Better for managing many projects efficiently
Ideal for scanning and project management tasks

Best Practices

Project Organization

Create projects for major initiatives:
- Product features: “Mosaic Features” for feature development
- Project phases: “Mosaic Phase 1”, “Mosaic Phase 2 (plans and subscriptions)”
- Time-bound projects: “Q1 2025 Launch”, “Annual Planning”
- Functional areas: “Customer Support”, “Infrastructure”
- Client engagements: “Client: Acme Corp Implementation”
Use descriptive names:
- Include phase information: “Mosaic Phase 2 (plans and subscriptions)”
- Be specific and clear: “Mobile App Redesign” not “App Work”
- Make names searchable: avoid abbreviations
- Consistent naming conventions across workspace
- Add context when helpful: “2025 Marketing Campaign”
Choose appropriate icons:
- Use meaningful emojis: ⭐ for important projects, 🚀 for launches
- Maintain consistent style within a space
- Pick colors that distinguish projects visually
- Make projects easy to identify at a glance
Set up lists logically within projects:
- Group by feature area: “Authentication”, “Payments”, “Dashboard”
- Organize by sprint/phase: “Sprint 1”, “Sprint 2”, “Backlog”
- Separate by workflow stage: “Planning”, “Development”, “Testing”
- Balance granularity: not too many tiny lists, not one huge list
Set project timelines:
- Define start date when project begins
- Set target date for accountability
- Update dates as project evolves
- Use dates for dashboard timeline tracking

Project Management

Monitor dashboard regularly:
- Check project Dashboard tab weekly for health insights
- Review task completion rates and identify trends
- Track team activity and performance metrics
- Identify delays and bottlenecks early
- Monitor velocity and adjust timelines if needed
- Use analytics for informed project decisions
Keep project team updated:
- Add new team members promptly during onboarding
- Remove departed members to maintain security
- Update member roles as responsibilities change
- Ensure manager assignment is current
- Review team composition regularly
Review tasks across lists:
- Use Tasks tab for holistic project view
- Understand cross-list dependencies and blockers
- Don’t focus on just one list - see the full picture
- Identify workload distribution across lists
- Coordinate work across multiple lists
Update project information:
- Keep description current in Info tab
- Update goals and objectives as project evolves
- Maintain accurate start and target dates
- Update status as project progresses (Backlog → In Progress → Completed)
- Adjust priority based on changing business needs
Leverage project privacy:
- Mark sensitive projects as private
- Keep internal projects public for transparency
- Review privacy settings when team changes
- Use private projects for confidential work
Archive completed projects:
- Archive instead of deleting to preserve history
- Use is_archived flag for completed projects
- Keep active project list manageable
- Access archived projects via API when needed

Task List Management

Create focused lists:
- Each list has clear, defined purpose
- Not too many lists: avoid overwhelming management (aim for 5-15 per project)
- Not too few lists: avoid mixing unrelated work
- Use list descriptions to clarify scope
Balance list sizes:
- Distribute tasks appropriately across lists
- Avoid one huge list with all tasks
- Break down large lists into focused sub-lists
- Monitor list task counts via sidebar
Use consistent naming:
- Follow project-level naming conventions
- Make list purpose clear from name: “Mosaic Quick Fixes”, “Mosaic Backlog Features”
- Aid navigation with descriptive names
- Prefix with project name if helpful for clarity
Manage list lifecycle:
- Create lists as needed for new work streams
- Archive completed lists to reduce clutter
- Monitor list count - too many indicates need for consolidation
- Use “Add New List” strategically

Troubleshooting

Can’t see a project

Possible reasons:

Not a member of the project
Wrong space selected
Wrong workspace selected
Insufficient Read permissions
Project may be archived

Solutions:

Check if you’re in the correct space via Space detail page
Verify workspace selection with workspace switcher at top of sidebar
Look in sidebar Projects section for all accessible projects
Search for project by name in Projects page
Request project access from project manager or space admin
Verify you have project membership
Contact workspace administrator if project should be visible

Can’t access project tasks

Possible reasons:

Insufficient Read permissions on MProject DocType
Not a project member
Lists within project are private and you’re not a list member
Project is archived
Wrong workspace selected

Solutions:

Request project membership from project manager
Check with project owner about access permissions
Verify workspace membership via Settings
Check if project is archived (look for archive indicator)
For private lists, request list-level access
Ensure you have Read permission on MProject DocType

Dashboard shows no data

Possible reasons:

Project has no tasks yet
Tasks lack required data fields (dates, status, assignees)
Dashboard calculating (may take moment on first load)
Insufficient permissions to view analytics
No lists in project yet

Solutions:

Verify project has task lists with tasks
Check if tasks have status, dates, and assignees set
Refresh the page to reload dashboard data
Wait a few seconds for dashboard calculations to complete
Check permissions - ensure you have Read access to project
Add tasks to project lists to see dashboard populate
Create lists in project if none exist

Lists not showing in Task Lists tab

Possible reasons:

No lists created in this project yet
Lists are private and you lack access
View filters hiding lists
Wrong project selected
Lists assigned to different project

Solutions:

Check Task Lists tab (default tab when opening project)
Switch between Board and List views - data may render differently
Verify lists are assigned to this specific project
Check if you have Read permission for lists
Review view filters - may be filtering out lists
Refresh the page to reload list data
Create new list if project is empty
Verify project name - ensure you’re in correct project

Can’t create new list in project

Possible reasons:

Insufficient Create permission on MTask List DocType
Project is archived
Project is locked (if locking feature exists)
Not a project member
Workspace permission restrictions

Solutions:

Verify you have Create permission on MTask List DocType
Check if project is archived - cannot add lists to archived projects
Look for ”+ Add Task List” button in sidebar or Task Lists tab
Try creating from different location: sidebar button, Task Lists tab, Lists page
Request project membership from project manager
Contact project admin or workspace administrator for permissions
Verify workspace membership and role

Can’t edit project settings

Possible reasons:

Insufficient Update permission on MProject DocType
Not a project member
Project is archived
Only certain fields restricted to project manager

Solutions:

Verify you have Update permission on MProject DocType
Check if you’re a project member (shown in header or Settings tab)
Ensure project is not archived
Request Update permissions from project manager
Contact workspace administrator for permission changes
Verify you’re assigned Admin role, not just User role

Project deletion fails

Possible reasons:

Insufficient Delete permission on MProject DocType
Did not type exact project title for confirmation
Project has dependent data (deletion protection)
System error or network issue

Solutions:

Ensure you have Delete permission on MProject DocType
Type the exact project title in confirmation field (case-sensitive)
Check console for error messages
Try refreshing page and attempting again
Contact system administrator if permission issues persist
Consider archiving instead of deleting to preserve data

Spaces - Projects belong to spaces (parent level)
Lists - Projects contain lists (child level)
Tasks - Working with tasks within project lists
Navigation & Sidebar - Navigating projects and workspace hierarchy

Project Fields Reference

Core Fields

Basic Information:

name: Unique identifier (UUID, auto-generated)
title: Project display name (required)
space: Parent space (required, Link to M Space)
workspace: Parent workspace (required, auto-fetched from space)
created_by: User who created the project (required, auto-set)
description: Rich text description of project purpose

Status and Priority:

status: Project status (Select, default: “Backlog”)
- Options: Backlog, ToDo, In Progress, In Review, On Hold, Blocked, Completed, Cancelled
priority: Project priority (Select, default: “Normal”)
- Options: Low, Normal, High, Urgent, Critical, Blocker
done: Completion flag (Check, default: 0)

Visual Identity:

icon: Emoji or icon for identification (Data)
color: Color theme for visual distinction (Color)
image: Attached image for project banner or avatar (Attach Image)

Dates:

start_date: Project start date (Date)
target_date: Project target completion date (Date)
executing_start_date: Execution start tracking (Date)
executing_end_date: Execution end tracking (Data)
created_date: Date project was created (Date, default: Today)
created_time: Time project was created (Time, default: Now)
last_edit_date: Date of last modification (Date)
last_edit_time: Time of last modification (Time)

Time Tracking:

time_needed: Estimated time needed in hours (Int, non-negative, default: 0)
total_duration: Total duration tracked (Int, non-negative)

Team and Access:

manager: Designated project manager (Link to User)
members: List of project team members with roles (Table, M Member child table)
subscribers: List of project subscribers for notifications (Table, MSubscribers child table)

Flags:

is_private: Privacy flag for access control (Check, default: 0)
is_archived: Archive status (Check, default: 0)
is_billable: Billable project indicator (Check, default: 0)

Source Tracking:

source_name: External source reference name (Data)
source_link: External source URL (Data)

Linked Documents

MTask List: Lists linked via project field in MTask List DocType

Permissions Model

Projects use the Mosaic permission system with workspace-based access control:

Permission Roles:

System Manager: Full access (Create, Read, Update, Delete, Export, Print, Email, Share, Report)
Mosaic Member: Full access (Create, Read, Update, Delete, Export, Print, Email, Share, Report)

Permission Checks:

Permission queries use get_permission_query_conditions_for_doctype("MProject")
Workspace-based permission inheritance
Project member access control
Private projects restrict visibility to members only

Document Behavior

Naming:

Auto-naming with UUID via generate_uuid() function
Name field is unique identifier across workspace

Inheritance:

Extends HierarchyManager class for hierarchical document management
Supports realtime updates via WebSocket for document changes
Propagates changes through document tree (Space → Project → List → Task)

Change Tracking:

track_changes: Enabled (all field changes tracked in version history)
Audit trail of all modifications

Workspace Context:

workspace field auto-fetched from parent space
Ensures project belongs to specific workspace for isolation

FAQ

Q: What’s the difference between a project and a list?

A: Projects are mid-level organizational containers that hold multiple lists. Lists are the direct containers for tasks. Think of projects as “initiatives” or “major work streams” (e.g., “Mosaic Phase 2”) and lists as specific collections of related tasks within that initiative (e.g., “Quick Fixes”, “Backlog Features”).

Q: Can a list be in multiple projects?

A: No, each list belongs to exactly one project. This maintains a clear organizational hierarchy. The list’s project field is a required Link field to MProject, enforcing single project membership.

Q: How many lists should a project have?

A: This depends on your workflow and project complexity. Examples from Mosaic show projects ranging from 5 lists (“Mosaic Features”) to 51 lists (“Mosaic Phase 3”). Aim for 5-15 lists per project for optimal management - too many lists become unwieldy, too few mix unrelated work.

Q: Can I see all tasks across multiple projects?

A: Yes. Use the global Tasks page to see all tasks across all projects and workspaces. To see tasks for a specific project, use the project’s Tasks tab, which shows all tasks from all lists in that project. The Tasks tab provides cross-list task visibility within a single project.

Q: Who can create projects?

A: Users with Create permission on the MProject DocType can create projects. This typically includes users with “Mosaic Member” or “System Manager” roles. Create permission is workspace-level, not project-specific.

Q: Can I move a list from one project to another?

A: Yes, you can reassign lists to different projects via the list Settings tab. Change the project field to move the list. This requires Update permission on the MTask List DocType. The list retains its tasks when moved.

Q: How do I archive a completed project?

A: Set the is_archived flag to true. Archived projects are hidden from normal views but preserve all data. Use the API endpoint get_archived_projects(space: str) to retrieve archived projects. Archiving is preferable to deletion for maintaining historical data.

Q: Can I set project deadlines or milestones?

A: Yes, use the Info tab to set Start Date and Target Date fields. These dates provide timeline tracking and are used in dashboard analytics for progress monitoring. The system validates that start date comes before target date.

Q: Do projects have permissions separate from spaces?

A: Yes, projects have their own member list and permission settings managed in the Settings tab. Project membership controls access to the project and its lists. Private projects (is_private: true) restrict visibility to project members only, regardless of space membership.

Q: What happens to lists and tasks when I delete a project?

A: Deleting a project permanently removes the project and all its data, including lists and tasks within those lists. This is a cascading deletion. Always confirm you want to delete by typing the exact project title. Consider archiving instead to preserve data.

Q: Can I change a project’s space?

A: Yes, you can reassign a project to a different space by editing the space field. The project’s workspace field will automatically update to match the new space’s workspace. This requires Update permission on the MProject DocType.

Q: What’s the difference between project manager and project members?

A: The project manager is a single designated user responsible for oversight and ownership. Project members are all team members with access to the project. The manager must be one of the project members and typically has broader responsibilities for project success.

Q: Can I duplicate a project?

A: Project duplication functionality depends on available actions in the project dropdown menu. Check the project actions menu (three dots) for duplicate options. Duplication may copy project settings but not necessarily all lists and tasks.

Q: How are project permissions enforced?

A: Projects use the Mosaic permission system with workspace-based access control. The get_permission_query_conditions_for_doctype("MProject") function checks workspace membership, project membership, and privacy settings. Private projects are only visible to members.