> For the complete documentation index, see [llms.txt](https://qbits-organization.gitbook.io/buildwise-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qbits-organization.gitbook.io/buildwise-doc/project-management..md). # Project Management. ### Create Project Creates a new project for the specified organisation. The authenticated user must have the OWNER or ADMIN role in the organisation. #### Endpoint ``` POST /api/v1/projects/{organisationId}/create ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier where the project will be created #### Request Body ```json { "name": "Website Redesign Project", "description": "Complete overhaul of company website with modern design", "contractNumber": "WEB-2025-001", "budget": 50000.00, "clientId": "456e7890-e12b-34c5-d678-901234567890" } ``` #### Validation Rules * `name`: Required, cannot be blank * `description`: Required, cannot be blank * `contractNumber`: Required, cannot be blank * `budget`: Optional, must be between 0.00 and 9,999,999,999,999.99 * `clientId`: Required, must be a valid client ID in the organisation * The project name must be unique within the organisation * The authenticated user must have the OWNER or ADMIN role in the organisation #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Project created successfully", "action_time": "2025-06-02T14:30:15.123456", "data": { "projectId": "123e4567-e89b-12d3-a456-426614174000", "projectCode": "PROJ0001" "name": "Website Redesign Project", "description": "Complete overhaul of company website with modern design", "contractNumber": "WEB-2025-001", "budget": 50000.00, "organisationName": "My Construction Company", "organisationId": "987fcdeb-51a2-43d1-9f12-123456789abc", "status": "ACTIVE", "createdAt": "2025-06-02T14:30:15.123456", "updatedAt": "2025-06-02T14:30:15.123456", "clientId": "456e7890-e12b-34c5-d678-901234567890", "clientName": "ABC Construction Ltd", "createdBy": "john.doe@example.com" } } ``` #### Error Responses * **404** - Organisation not found, client not found in organisation, member not found in organisation, or insufficient permissions * **400** - Budget value is too large, missing required fields, project name already exists, or invalid data provided * **401** - Unauthorized (invalid token) * **500** - An unexpected error occurred while creating the project *** ### Get Project By ID Retrieves a project by its ID. The authenticated user must be a team member of the project. #### Endpoint ``` GET /api/v1/projects/{projectId} ``` #### Path Parameters * `projectId` (UUID) - The project identifier #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Project retrieved successfully", "action_time": "2025-06-02T14:35:20.654321", "data": { "projectId": "123e4567-e89b-12d3-a456-426614174000", "projectCode": "PROJ0001" "name": "Website Redesign Project", "description": "Complete overhaul of company website with modern design", "contractNumber": "WEB-2025-001", "budget": 50000.00, "organisationName": "My Software Company", "organisationId": "987fcdeb-51a2-43d1-9f12-123456789abc", "status": "ACTIVE", "createdAt": "2025-06-02T14:30:15.123456", "updatedAt": "2025-06-02T14:30:15.123456", "clientId": "456e7890-e12b-34c5-d678-901234567890", "clientName": "ABC Construction Ltd", "createdBy": "john.doe@example.com" } } ``` #### Error Responses * **404** - Project not found * **403** - Access denied (user is not a team member of the project) * **401** - Unauthorized *** ### Update Project Updates an existing project's details. The authenticated user must have OWNER or ADMIN role in the organisation and be a team member of the project. #### Endpoint ``` PUT /api/v1/projects/{projectId} ``` #### Path Parameters * `projectId` (UUID) - The project identifier to update #### Request Body ```json { "name": "Updated Project Name", "description": "Updated project description", "contractNumber": "WEB-2025-002", "budget": 75000.00 } ``` #### Update Rules * Only the provided fields are updated * Empty or null values preserve existing data * Only OWNER or ADMIN members can update projects * User must be a team member of the project * Name must be unique within the organisation if it is changed #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Project updated successfully", "action_time": "2025-06-02T15:00:25.345678", "data": { "projectId": "123e4567-e89b-12d3-a456-426614174000", "projectCode": "PROJ0001" "name": "Updated Project Name", "description": "Updated project description", "contractNumber": "WEB-2025-002", "budget": 75000.00, "organisationName": "My Software Company", "organisationId": "987fcdeb-51a2-43d1-9f12-123456789abc", "status": "ACTIVE", "createdAt": "2025-06-02T14:30:15.123456", "updatedAt": "2025-06-02T15:00:25.345678", "clientId": "456e7890-e12b-34c5-d678-901234567890", "clientName": "ABC Construction Ltd", "createdBy": "john.doe@example.com" } } ``` #### Error Responses * **404** - Project not found, member not found in organisation, insufficient permissions, or duplicate name * **403** - Access denied (user is not a team member or lacks permissions) * **400** - Budget value is too large, missing required fields, or invalid data provided * **401** - Unauthorized * **500** - An unexpected error occurred while updating the project *** ### Delete Project Soft deletes a project by marking it as DELETED. The authenticated user must have OWNER or ADMIN role in the organisation. #### Endpoint ``` DELETE /api/v1/projects/{projectId} ``` #### Path Parameters * `projectId` (UUID) - The project identifier to delete #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Project deleted successfully", "action_time": "2025-06-02T15:10:30.789123", "data": null } ``` #### Error Responses * **404** - Project not found or insufficient permissions * **403** - Access denied (insufficient permissions) * **401** - Unauthorized * **500** - Failed to delete project *** ### Get Organisation Projects Retrieves paginated projects for an organisation. The authenticated user must be an active member of the organisation. #### Endpoint ``` GET /api/v1/projects/organisation/{organisationId} ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier #### Query Parameters * `page` (integer, default: 0) - Page number (zero-based) * `size` (integer, default: 10) - Page size #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Organisation projects retrieved successfully", "action_time": "2025-06-02T15:15:45.234567", "data": { "content": [ { "projectId": "123e4567-e89b-12d3-a456-426614174000", "projectCode": "PROJ0001" "name": "Website Redesign Project", "description": "Complete overhaul of company website", "contractNumber": "WEB-2025-001", "budget": 50000.00, "status": "ACTIVE", "organisationName": "My Software Company", "organisationId": "987fcdeb-51a2-43d1-9f12-123456789abc", "createdAt": "2025-06-02T14:30:15.123456", "updatedAt": "2025-06-02T14:30:15.123456", "clientId": "456e7890-e12b-34c5-d678-901234567890", "clientName": "ABC Construction Ltd", "createdBy": "john.doe@example.com" } ], "pageable": { "pageNumber": 0, "pageSize": 10, "sort": { "sorted": true, "unsorted": false, "empty": false }, "offset": 0, "paged": true, "unpaged": false }, "totalElements": 8, "totalPages": 1, "first": true, "last": true, "numberOfElements": 1, "size": 10, "number": 0, "sort": { "sorted": true, "unsorted": false, "empty": false }, "empty": false } } ``` #### Error Responses * **404** - Organisation not found or member not found in organisation * **401** - Unauthorized ### Get My Projects in Organisation, I belong Retrieves paginated projects where the authenticated user is a team member in the specified organisation. This endpoint returns only projects that the user is actively participating in as a team member. ``` GET /api/v1/projects/organisation/{organisationId}/my-projects ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier #### Query Parameters * `page` (integer, default: 0) - Page number (zero-based) * `size` (integer, default: 10) - Page size #### Access Requirements * User must be an active member of the organisation * User must be a team member of the projects returned * Only non-deleted projects are included in the results #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "My projects retrieved successfully", "action_time": "2025-06-02T16:20:30.987654", "data": { "content": [ { "projectId": "123e4567-e89b-12d3-a456-426614174000", "projectCode": "PROJ0001", "name": "Website Redesign Project", "description": "Complete overhaul of company website", "contractNumber": "WEB-2025-001", "budget": 50000.00, "status": "ACTIVE", "organisationName": "My Software Company", "organisationId": "987fcdeb-51a2-43d1-9f12-123456789abc", "createdAt": "2025-06-02T14:30:15.123456", "updatedAt": "2025-06-02T14:30:15.123456", "clientId": "456e7890-e12b-34c5-d678-901234567890", "clientName": "ABC Construction Ltd", "createdBy": "john.doe@example.com" }, { "projectId": "456e7890-e12b-34c5-d678-901234567890", "projectCode": "PROJ0002", "name": "Mobile App Development", "description": "Cross-platform mobile application", "contractNumber": "MOB-2025-001", "budget": 75000.00, "status": "ACTIVE", "organisationName": "My Software Company", "organisationId": "987fcdeb-51a2-43d1-9f12-123456789abc", "createdAt": "2025-06-01T10:15:30.456789", "updatedAt": "2025-06-01T10:15:30.456789", "clientId": "789f0123-e45b-67c8-d901-234567890abc", "clientName": "XYZ Tech Solutions", "createdBy": "jane.smith@example.com" } ], "pageable": { "pageNumber": 0, "pageSize": 10, "sort": { "sorted": true, "unsorted": false, "empty": false }, "offset": 0, "paged": true, "unpaged": false }, "totalElements": 2, "totalPages": 1, "first": true, "last": true, "numberOfElements": 2, "size": 10, "number": 0, "sort": { "sorted": true, "unsorted": false, "empty": false }, "empty": false } } ``` #### Error Responses * **404** - Organisation not found or member not found in organisation * **401** - Unauthorized ### Authentication & Authorization #### General Rules * All endpoints require authentication via a JWT token * Users must be active members of the relevant organisation * Project creation and updates require the OWNER or ADMIN role * Project access requires team membership in the project * Project deletion requires the OWNER or ADMIN role #### Common Error Responses All endpoints may return: * **401 Unauthorized** - Invalid or missing authentication token * **500 Internal Server Error** - Unexpected server error ### Response Format All successful responses follow this structure: ```json { "success": true, "httpStatus": "OK", "message": "Description of the operation", "action_time": "2025-06-02T15:45:30.123456", "data": { /* Response data or null */ } } ``` ### Additional Notes #### Project Status Projects have the following possible statuses: * `ACTIVE` - Default status for new projects * `DELETED` - Soft deleted projects (not physically removed from the database) #### Team Member Management * When a project is created, the creator is automatically added as a team member * The organisation owner is also automatically added as a team member * Users must be team members to access project details #### Client Integration * Projects must be associated with a client from the same organisation * Client information is included in all project responses