Project Creation API

Project Creation API

The Project Creation API allows clients and administrators to create, manage, and update projects while integrating key components such as Schedule of Quantities (SOQ), teams, and roles.

---

1. Overview

The Project Creation API enables:

1. New Project Creation: Initialize projects with details like name, location, and budget.
2. Linking SOQ: Attach SOQs to estimate project costs.
3. Role and Team Assignment: Manage team members with assigned roles.
4. Project Updates: Modify project visibility, milestones, and phases.

---

2. API Endpoints

Create New Project

Endpoint:

POST /api/project/create

Description:
Creates a new project entity with initial details.

Request Body:

Field	Type	Required	Description
projectName	string	✅	Name of the project
description	string	✅	Brief description of the project
location	string	✅	Location of the project
budget	number	✅	Estimated project budget
startDate	string	✅	Project start date (YYYY-MM-DD)
endDate	string	✅	Project end date (YYYY-MM-DD)
visibility	string	✅	Public or private project visibility
creatorId	string	✅	User ID of the project creator

Response:

{
  "success": true,
  "projectId": "proj-12345",
  "status": "created",
  "message": "Project created successfully."
}

---

Attach SOQ to Project

Endpoint:

POST /api/project/attach-soq

Description:
Links an existing SOQ to a project for cost estimation and tender management.

Request Body:

Field	Type	Required	Description
projectId	string	✅	Unique ID of the project
soqId	string	✅	Unique ID of the SOQ
linkedBy	string	✅	User ID of the person linking SOQ

Response:

{
  "success": true,
  "message": "SOQ linked to project successfully.",
  "projectId": "proj-12345",
  "soqId": "soq-67890"
}

---

Assign Roles and Teams

Endpoint:

POST /api/project/assign-roles

Description:
Assigns roles and permissions to team members for a project.

Request Body:

Field	Type	Required	Description
projectId	string	✅	Unique ID of the project
userId	string	✅	ID of the user to assign the role
role	string	✅	Role of the user (e.g., Manager, Engineer)

Response:

{
  "success": true,
  "message": "Role assigned successfully.",
  "projectId": "proj-12345",
  "userId": "user-56789",
  "role": "Project Manager"
}

---

Update Project Details

Endpoint:

PUT /api/project/update/:projectId

Description:
Updates project details such as budget, timeline, or description.

Path Parameter:

• projectId: Unique ID of the project.

Request Body:

Field	Type	Required	Description
description	string	❌	Updated project description
budget	number	❌	Updated budget amount
endDate	string	❌	Updated end date (YYYY-MM-DD)

Response:

{
  "success": true,
  "message": "Project updated successfully.",
  "projectId": "proj-12345",
  "updatedFields": {
    "description": "New project description",
    "budget": 1000000,
    "endDate": "2025-12-31"
  }
}

---

Get Project Details

Endpoint:

GET /api/project/details/:projectId

Description:
Fetches detailed information about a specific project.

Path Parameter:

• projectId: Unique ID of the project.

Response:

{
  "projectId": "proj-12345",
  "projectName": "City Center High-Rise",
  "description": "A modern commercial skyscraper project.",
  "location": "Auckland, New Zealand",
  "budget": 15000000,
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "visibility": "public",
  "status": "in-progress",
  "linkedSOQ": "soq-67890",
  "teamMembers": [
    { "userId": "user-56789", "role": "Project Manager" },
    { "userId": "user-67890", "role": "Site Engineer" }
  ]
}

---

3. Use Case: Project Creation Flow

1. Client creates a new project using /api/project/create.
2. SOQ is linked to the project via /api/project/attach-soq.
3. Roles and Teams are assigned using /api/project/assign-roles.
4. Project details are updated and tracked through /api/project/update and /api/project/details.

---

4. Error Codes

Code	Description
400	Invalid request or missing parameters
404	Project ID or SOQ not found
403	Unauthorized access to update project data
500	Internal server error

---

5. Security Considerations

• Role-Based Access Control (RBAC): Ensures only authorized users can create, update, or manage projects.
• Input Validation: Prevents malformed requests.
• Blockchain Integration: Project IDs are stored on-chain for transparency and immutability.

---

Summary

The Project Creation API in 14Build allows users to create, update, and manage projects efficiently. It integrates with SOQs, roles, and teams while maintaining on-chain transparency for all stakeholders.

---

Next Steps

Explore how tenders are managed through the Tender Management API in tender-management.md.

---