📑 Strategize API Documentation

Welcome to the Strategize GraphQL & File-Storage API. Frontend teams, here’s what you need:

🚀 GraphQL Endpoint

• URL: POST /graphql
• Playground: available at the same URL in dev
• Auth: send header Authorization: Bearer <JWT_TOKEN>

Authentication

1. Seeded Super-Admin on first run:

   • Email: johndoe@email.com
   • Password: qwerty123

2. Login Mutation

   mutation Login($input: LoginEmployeeInput!) {
     loginEmployee(loginInput: $input) {
       accessToken
       employee {
         employeeId
         fullName
         email
         role
       }
     }
   }
   

   Use the returned accessToken for all subsequent requests.

“Who am I?” Query

query {
  me {
    employeeId
    fullName
    email
    role
    status
    startDate
  }
}

👥 Employee CRUD (all require JWT)

Each employees query now supports optional full-text search on fullName and email, plus pagination.

query Employees($search: String, $page: Int, $limit: Int) {
  employees(search: $search, page: $page, limit: $limit) {
    items {
      employeeId
      fullName
      email
      role
      departments {
        departmentId
        name
      }
    }
    meta {
      totalItems
      itemCount
      itemsPerPage
      totalPages
      currentPage
    }
  }
}

mutation CreateEmployee($input: CreateEmployeeInput!) {
  createEmployee(createEmployeeInput: $input) {
    employeeId
    fullName
    email
    role
  }
}

mutation UpdateEmployee($input: UpdateEmployeeInput!) {
  updateEmployee(updateEmployeeInput: $input) {
    employeeId
    fullName
    email
    role
  }
}

mutation RemoveEmployee($id: ID!) {
  removeEmployee(employeeId: $id) {
    employeeId
    fullName
  }
}

🏢 Division CRUD (supports search & pagination)

query Divisions($search: String, $page: Int, $limit: Int) {
  divisions(search: $search, page: $page, limit: $limit) {
    items {
      divisionId
      name
      manager {
        employeeId
        fullName
      }
      departments {
        departmentId
        name
      }
    }
    meta {
      totalItems
      itemCount
      itemsPerPage
      totalPages
      currentPage
    }
  }
}

mutation CreateDivision($input: CreateDivisionInput!) {
  createDivision(createDivisionInput: $input) {
    divisionId
    name
  }
}

mutation UpdateDivision($input: UpdateDivisionInput!) {
  updateDivision(updateDivisionInput: $input) {
    divisionId
    name
  }
}

mutation RemoveDivision($id: ID!) {
  removeDivision(divisionId: $id) {
    divisionId
    name
  }
}

🏬 Department CRUD & Relations (supports search & pagination)

query Departments($search: String, $page: Int, $limit: Int) {
  departments(search: $search, page: $page, limit: $limit) {
    items {
      departmentId
      name
      manager {
        employeeId
        fullName
      }
      division {
        divisionId
        name
      }
      employees {
        employeeId
        fullName
      }
    }
    meta {
      totalItems
      itemCount
      itemsPerPage
      totalPages
      currentPage
    }
  }
}

mutation CreateDepartment($input: CreateDepartmentInput!) {
  createDepartment(createDepartmentInput: $input) {
    departmentId
    name
  }
}

mutation UpdateDepartment($input: UpdateDepartmentInput!) {
  updateDepartment(updateDepartmentInput: $input) {
    departmentId
    name
  }
}

mutation RemoveDepartment($id: ID!) {
  removeDepartment(departmentId: $id) {
    departmentId
    name
  }
}

🔗 Department-Employee Relations

mutation AddEmployeeToDept($deptId: ID!, $empId: ID!) {
  addEmployeeToDepartment(departmentId: $deptId, employeeId: $empId) {
    departmentId
    name
    employees {
      employeeId
      fullName
    }
  }
}

mutation RemoveEmployeeFromDept($deptId: ID!, $empId: ID!) {
  removeEmployeeFromDepartment(departmentId: $deptId, employeeId: $empId) {
    departmentId
    name
    employees {
      employeeId
      fullName
    }
  }
}

📅 StrategicPeriod CRUD (auto-compute endDate, createdBy from current user)

query StrategicPeriods($page: Int, $limit: Int) {
  strategicPeriods(page: $page, limit: $limit) {
    items {
      strategicPeriodId
      startDate
      length
      endDate
      createdBy {
        employeeId
        fullName
      }
    }
    meta {
      totalItems
      itemCount
      itemsPerPage
      totalPages
      currentPage
    }
  }
}

mutation CreateStrategicPeriod($input: CreateStrategicPeriodInput!) {
  createStrategicPeriod(createStrategicPeriodInput: $input) {
    strategicPeriodId
    startDate
    length
    endDate
  }
}

mutation UpdateStrategicPeriod($input: UpdateStrategicPeriodInput!) {
  updateStrategicPeriod(updateStrategicPeriodInput: $input) {
    strategicPeriodId
    startDate
    length
    endDate
  }
}

mutation RemoveStrategicPeriod($id: ID!) {
  removeStrategicPeriod(strategicPeriodId: $id) {
    strategicPeriodId
  }
}

🎯 Objective CRUD, Assignment & Relations (supports search, pagination, assignment)

• Objectives can be assigned to other users, with support for parent/child objectives and KPI inheritance.
• Each objective can have an assignee, assigner, parent, and a list of KPIs.

Query Objectives (with all relations)

query Objectives($search: String, $page: Int, $limit: Int, $assigneeId: ID) {
  objectives(
    search: $search
    page: $page
    limit: $limit
    assigneeId: $assigneeId
  ) {
    items {
      objectiveId
      name
      type
      status
      strategicPeriod {
        strategicPeriodId
        startDate
      }
      createdBy {
        employeeId
        fullName
      }
      assignee {
        employeeId
        fullName
      }
      assigner {
        employeeId
        fullName
      }
      parent {
        objectiveId
        name
      }
      kpis {
        kpiId
        name
        status
        parentId
        assigneeId
      }
    }
    meta {
      totalItems
      itemCount
      itemsPerPage
      totalPages
      currentPage
    }
  }
}

Assign Objective (with KPI inheritance)

mutation AssignObjective($input: AssignObjectiveInput!) {
  assignObjective(assignObjectiveInput: $input) {
    objectiveId
    parent {
      objectiveId
      name
    }
    assignee {
      employeeId
      fullName
    }
    assigner {
      employeeId
      fullName
    }
    kpis {
      kpiId
      name
      parentId
      assigneeId
      status
    }
    createdBy {
      employeeId
      fullName
    }
  }
}

Example AssignObjectiveInput

{
  "objectiveId": "<parentObjectiveId>",
  "assigneeId": "<employeeId>",
  "assignerId": "<managerId>",
  "assigneeType": "INDIVIDUAL",
  "kpis": ["<kpiId1>", "<kpiId2>"]
}

• When assigning, a new child objective is created, linked to the parent, and selected KPIs are cloned and assigned to the new objective/assignee.
• The response includes all relations for easy frontend rendering.

📊 KPI CRUD (supports search & pagination, targets as JSON array)

query Kpis($search: String, $page: Int, $limit: Int) {
  kpis(search: $search, page: $page, limit: $limit) {
    items {
      kpiId
      name
      unitType
      weight
      status
      baseline
      targets {
        timeline
        target
      }
      objective {
        objectiveId
      }
    }
    meta {
      totalItems
      itemCount
      itemsPerPage
      totalPages
      currentPage
    }
  }
}

mutation CreateKpi($input: CreateKpiInput!) {
  createKpi(createKpiInput: $input) {
    kpiId
    name
    status
  }
}

mutation UpdateKpi($input: UpdateKpiInput!) {
  updateKpi(updateKpiInput: $input) {
    kpiId
    name
    status
  }
}

mutation RemoveKpi($id: ID!) {
  removeKpi(kpiId: $id) {
    kpiId
  }
}

Update KPI Order

You can update a single KPI's order or multiple KPIs at once.

mutation UpdateKpiOrder($input: UpdateKpiOrderInput!) {
  updateKpiOrder(updateKpiOrderInput: $input) {
    kpiId
    name
    order
  }
}

Example UpdateKpiOrderInput (single)

{
  "kpiId": "<kpiId>",
  "order": 2
}

Example: Update Multiple KPI Orders

mutation UpdateMultipleKpiOrders($inputs: [UpdateKpiOrderInput!]!) {
  updateKpiOrders(updateKpiOrderInputs: $inputs) {
    kpiId
    name
    order
  }
}

[
  {
    "kpiId": "<kpiId1>",
    "order": 1
  },
  {
    "kpiId": "<kpiId2>",
    "order": 2
  },
  {
    "kpiId": "<kpiId3>",
    "order": 3
  }
]

🎯 Objective CRUD, Assignment & Relations (supports search, pagination, assignment)

• Objectives can be assigned to other users, with support for parent/child objectives and KPI inheritance.
• Each objective can have an assignee, assigner, parent, and a list of KPIs.

Query Objectives (with all relations)

query Objectives($search: String, $page: Int, $limit: Int, $assigneeId: ID) {
  objectives(
    search: $search
    page: $page
    limit: $limit
    assigneeId: $assigneeId
  ) {
    items {
      objectiveId
      name
      type
      status
      strategicPeriod {
        strategicPeriodId
        startDate
      }
      createdBy {
        employeeId
        fullName
      }
      assignee {
        employeeId
        fullName
      }
      assigner {
        employeeId
        fullName
      }
      parent {
        objectiveId
        name
      }
      kpis {
        kpiId
        name
        status
        parentId
        assigneeId
      }
    }
    meta {
      totalItems
      itemCount
      itemsPerPage
      totalPages
      currentPage
    }
  }
}

Assign Objective (with KPI inheritance)

mutation AssignObjective($input: AssignObjectiveInput!) {
  assignObjective(assignObjectiveInput: $input) {
    objectiveId
    parent {
      objectiveId
      name
    }
    assignee {
      employeeId
      fullName
    }
    assigner {
      employeeId
      fullName
    }
    kpis {
      kpiId
      name
      parentId
      assigneeId
      status
    }
    createdBy {
      employeeId
      fullName
    }
  }
}

Example AssignObjectiveInput

{
  "objectiveId": "<parentObjectiveId>",
  "assigneeId": "<employeeId>",
  "assignerId": "<managerId>",
  "assigneeType": "INDIVIDUAL",
  "kpis": ["<kpiId1>", "<kpiId2>"]
}

• When assigning, a new child objective is created, linked to the parent, and selected KPIs are cloned and assigned to the new objective/assignee.
• The response includes all relations for easy frontend rendering.

Update Objective Order

You can update a single objective's order or multiple objectives at once.

mutation UpdateObjectiveOrder($input: UpdateObjectiveOrderInput!) {
  updateObjectiveOrder(updateObjectiveOrderInput: $input) {
    objectiveId
    name
    order
  }
}

Example UpdateObjectiveOrderInput (single)

{
  "objectiveId": "<objectiveId>",
  "order": 1
}

Example: Update Multiple Objective Orders

mutation UpdateMultipleObjectiveOrders($inputs: [UpdateObjectiveOrderInput!]!) {
  updateObjectiveOrders(updateObjectiveOrderInputs: $inputs) {
    objectiveId
    name
    order
  }
}

[
  {
    "objectiveId": "<objectiveId1>",
    "order": 1
  },
  {
    "objectiveId": "<objectiveId2>",
    "order": 2
  },
  {
    "objectiveId": "<objectiveId3>",
    "order": 3
  }
]

📂 File Storage (REST)

• Upload

  POST /upload
  Content-Type: multipart/form-data
  Body: { file: <binary> }
  

  → returns { url, filename, originalname, size, type }

• Download

  GET /storage/:filename
  

  → streams the file back

📝 Submission CRUD & Flows

• All submission endpoints require JWT authentication.
• Submissions can be created for objectives or KPIs, and support both single and bulk creation.
• Each submission tracks who submitted, its type, level, status, and references either an objective or a KPI.

Query Submissions (with pagination and type filter)

query Submissions($page: Int, $limit: Int, $type: ObjectiveType!) {
  submissions(page: $page, limit: $limit, type: $type) {
    items {
      submissionId
      type
      level
      status
      reason
      submittedBy {
        employeeId
        fullName
      }
      objective {
        objectiveId
        name
      }
      kpi {
        kpiId
        name
      }
      createdAt
    }
    meta {
      totalItems
      itemCount
      itemsPerPage
      totalPages
      currentPage
    }
  }
}

Query Single Submission

query Submission($id: ID!) {
  submission(submissionId: $id) {
    submissionId
    type
    level
    status
    reason
    submittedBy {
      fullName
    }
    objective {
      name
    }
    kpi {
      name
    }
    createdAt
  }
}

Create a Submission

mutation CreateSubmission($input: CreateSubmissionInput!) {
  createSubmission(createSubmissionInput: $input) {
    submissionId
    type
    level
    status
    reason
    createdAt
  }
}

Example CreateSubmissionInput

{
  "type": "OBJECTIVE",
  "level": "INDIVIDUAL",
  "itemId": "<objectiveId>",
  "reason": "Completed milestone 1"
}

Create Multiple Submissions

mutation CreateSubmissions($inputs: [CreateSubmissionInput!]!) {
  createSubmissions(createSubmissionInputs: $inputs) {
    submissionId
    type
    level
    status
    reason
    createdAt
  }
}

Example createSubmissionInputs array

[
  {
    "type": "OBJECTIVE",
    "level": "INDIVIDUAL",
    "itemId": "<objectiveId>",
    "reason": "Completed milestone 1"
  },
  {
    "type": "KPI",
    "level": "TEAM",
    "itemId": "<kpiId>",
    "reason": "Exceeded Q2 target"
  }
]

Update a Submission

mutation UpdateSubmission($input: UpdateSubmissionInput!) {
  updateSubmission(updateSubmissionInput: $input) {
    submissionId
    status
    reason
    updatedAt
  }
}

Remove a Submission

mutation RemoveSubmission($id: ID!) {
  removeSubmission(submissionId: $id) {
    submissionId
    status
  }
}

1. Hit /readme in your browser for the HTML docs (dark mode)
2. Hit /readme.md for raw Markdown
3. Hit /api for Swagger, /graphql for Playground

Happy building! 🚀