SyncFlow

Decentralized board and task coordination dApp on the Sui blockchain.

Current testnet package ID: 0xa8432da223503968a2c93317ca027aa49c222eeca2ea5cd56fb37a4139fe1452

⚡ Judge Quickstart (frontend)

cd app/syncflow
npm install
npm run dev  # http://localhost:5173

Production build (static output in app/syncflow/dist):

npm run build

🎯 Overview

SyncFlow is a full-stack decentralized project management system built on Sui. It includes Move smart contracts for on-chain task coordination and a TypeScript SDK for seamless frontend integration.

📁 Project Structure

SyncFlow/
├── move/syncflow/          # Sui Move smart contracts
│   ├── sources/            # Contract source files
│   │   ├── board.move      # Board management
│   │   ├── task.move       # Task & subtask management
│   │   ├── models.move     # Shared models & constants
│   │   └── permissions.move # Authorization helpers
│   └── tests/              # Move test suite (28 tests)
│
├── typescript/             # TypeScript SDK for frontend
│   ├── src/
│   │   ├── client/         # SyncFlowClient for blockchain interaction
│   │   ├── hooks/          # React Query hooks
│   │   ├── types/          # TypeScript type definitions
│   │   ├── config/         # Configuration & constants
│   │   ├── utils/          # Utility functions
│   │   ├── contexts/       # React context providers
│   │   └── services/       # Event listeners
│   └── package.json
│
└── app/                    # Frontend application (React)

🏗️ Architecture

Modules

Smart Contracts (Move)

Modules

• board.move - Board storage, roles, and metadata management
• task.move - Tasks, subtasks, and participant logic
• models.move - Shared data structures and constants
• permissions.move - Permission verification helpers

Key Features

✅ Role-based access control (Admin & Contributor roles)
✅ Board creation and management
✅ Task lifecycle management (ToDo → InProgress → Review → Done)
✅ Task deletion (admin only)
✅ Participant management
✅ Invitations (add admin/contributor)
✅ Event emission for all major actions
✅ Comprehensive test suite (28 tests passing)

TypeScript SDK

• Type-Safe: Full TypeScript definitions matching Move structs
• React Hooks: Ready-to-use hooks with React Query integration
• Transaction Builders: Easy transaction construction for all operations
• Event Listeners: Real-time contract event subscriptions
• Utilities: Formatters, validators, statistics helpers

🔐 Roles & Permissions

Admin Role

• Board creator is automatically an admin
• Can add/remove other admins
• Can add/remove contributors
• Can create, edit, and delete tasks
• Can create, edit, and delete subtasks
• Can update board metadata
• Can manage participants

Contributor Role

• Can create tasks
• Can edit tasks
• Can update task status
• Can create and edit subtasks
• Can manage participants
• Cannot delete tasks or subtasks
• Cannot manage board members
• Cannot change board metadata

📦 Data Structures

Board

struct Board has key {
    id: UID,
    name: String,
    description: String,
    owner: address,
    admins: Table<address, bool>,
    contributors: Table<address, bool>,
    task_ids: vector<ID>,
    created_at: u64,
    updated_at: u64,
}

Task

struct Task has key {
    id: UID,
    board_id: ID,
    name: String,
    description: String,
    status: u8,               // 0=ToDo, 1=InProgress, 2=Review, 3=Done
    participants: vector<address>,
    created_by: address,
    due_date: u64,
    created_at: u64,
    updated_at: u64,
    subtasks: vector<ID>,
}

Subtask

struct Subtask has key {
    id: UID,
    task_id: ID,
    name: String,
    description: String,
    completed: bool,
}

🚀 Getting Started

Prerequisites

• Sui CLI for smart contract deployment
• Node.js 18+ and npm for TypeScript/React development

1. Deploy Smart Contracts

cd move/syncflow
sui move build
sui move test  # Verify all 28 tests pass
sui client publish --gas-budget 100000000

Save the PACKAGE_ID from the deployment output.

2. Set Up TypeScript SDK

cd typescript
npm install

# Create .env file
cp .env.example .env
# Update REACT_APP_PACKAGE_ID with your deployed package ID

3. Build TypeScript SDK

npm run build    # Compile TypeScript
npm run dev      # Watch mode for development
npm test         # Run tests

💻 TypeScript SDK Usage

Initialize Provider

import { SyncFlowProvider } from './typescript/src';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <SyncFlowProvider packageId="YOUR_PACKAGE_ID">
        <YourApp />
      </SyncFlowProvider>
    </QueryClientProvider>
  );
}

Use Query Hooks

import { useBoard, useBoardTasks } from './typescript/src';

function BoardView({ boardId }: { boardId: string }) {
  const { data: board, isLoading } = useBoard(boardId);
  const { data: tasks } = useBoardTasks(boardId);

  if (isLoading) return <div>Loading...</div>;
  
  return (
    <div>
      <h1>{board?.name}</h1>
      <p>{board?.description}</p>
      <div>Tasks: {tasks?.length}</div>
    </div>
  );
}

Use Mutation Hooks

import { 
  useCreateTaskMutation, 
  useUpdateTaskStatusMutation 
} from './typescript/src';

function TaskCreator({ boardId }: { boardId: string }) {
  const createTask = useCreateTaskMutation();
  const updateStatus = useUpdateTaskStatusMutation();

  const handleCreate = async () => {
    await createTask.mutateAsync({
      boardId,
      name: "New Task",
      description: "Task description",
      dueDate: Date.now() + 86400000, // 24 hours from now
    });
  };

  const handleUpdateStatus = async (taskId: string) => {
    await updateStatus.mutateAsync({
      boardId,
      taskId,
      newStatus: 1, // InProgress
    });
  };

  return <button onClick={handleCreate}>Create Task</button>;
}

🚀 Move Contract Usage

Board Operations

Create Board

board::create_board(name, description, clock, ctx)

Update Board (Admin only)

board::update_board(board, new_name, new_description, clock, ctx)

Manage Admins (Admin only)

board::add_admin(board, user_address, clock, ctx)
board::remove_admin(board, user_address, clock, ctx)

Manage Contributors (Admin only)

board::add_contributor(board, user_address, clock, ctx)
board::remove_contributor(board, user_address, clock, ctx)

Task Operations

Create Task (Admin or Contributor)

task::create_task(board, name, description, due_date, clock, ctx)

Update Task (Admin or Contributor)

task::update_task(board, task, name, description, due_date, clock, ctx)
task::update_task_status(board, task, new_status, clock, ctx)

Delete Task (Admin only)

task::delete_task(board, task, clock, ctx)

Manage Participants (Admin or Contributor)

task::add_participant(board, task, user_address, clock, ctx)
task::remove_participant(board, task, user_address, clock, ctx)

Subtask Operations

Create Subtask (Admin or Contributor)

task::create_subtask(board, task, name, description, clock, ctx)

Update Subtask (Admin or Contributor)

task::update_subtask(board, subtask, name, description, clock, ctx)
task::toggle_subtask_status(board, subtask, clock, ctx)

Delete Subtask (Admin only)

task::delete_subtask(board, task, subtask, clock, ctx)

📊 Task Status Values

• 0 - ToDo
• 1 - InProgress
• 2 - Review
• 3 - Done

🧪 Test Coverage

Board Tests (board_tests.move)

• ✅ Board creation
• ✅ Board updates
• ✅ Admin management
• ✅ Contributor management
• ✅ Permission enforcement
• ✅ Owner protection (owner cannot be removed as admin)
• ✅ Multiple admins and contributors

Task Tests (task_tests.move)

• ✅ Task creation by admin
• ✅ Task creation by contributor
• ✅ Task updates
• ✅ Status transitions
• ✅ Task deletion (admin only)
• ✅ Participant management
• ✅ Subtask lifecycle
• ✅ Subtask status toggling
• ✅ Subtask deletion (admin only)
• ✅ Permission enforcement
• ✅ Complete task lifecycle (ToDo → InProgress → Review → Done)

🔥 Events

The system emits events for all major operations:

Board Events

• BoardCreated
• BoardUpdated
• AdminAdded / AdminRemoved
• ContributorAdded / ContributorRemoved
• TaskRegistered / TaskRemoved

Task Events

• TaskCreated
• TaskUpdated
• TaskStatusChanged
• TaskDeleted
• ParticipantAdded / ParticipantRemoved

Subtask Events

• SubtaskCreated
• SubtaskUpdated
• SubtaskStatusToggled
• SubtaskDeleted

🛡️ Error Codes

Board Module

• 201 - ENotAdmin: User is not an admin
• 202 - ECannotRemoveOwner: Cannot remove board owner as admin
• 203 - ETaskNotFound: Task ID not found in board

Task Module

• 300 - EInvalidStatus: Invalid task status value
• 302 - EParticipantNotFound: Participant not found in task
• 303 - ESubtaskNotFound: Subtask not found in task

Permissions Module

• 100 - ENotAdmin: User is not an admin
• 101 - ENotContributor: User is not a contributor
• 102 - ENotAuthorized: User is neither admin nor contributor

🚢 Deployment Checklist

• Update Move.toml with deployment addresses
• Run sui move build successfully
• Run sui move test - all 28 tests pass
• Deploy with sui client publish --gas-budget 100000000
• Save PACKAGE_ID from deployment
• Update .env in typescript folder with PACKAGE_ID
• Build TypeScript SDK with npm run build
• Verify no TypeScript compilation errors

🧪 Testing

Move Contracts

cd move/syncflow
sui move test

Test Results: All 28 tests passing

• 13 board management tests
• 15 task/subtask tests

TypeScript SDK

cd typescript
npm test

📝 Development Status

✅ Smart contracts complete and tested
✅ TypeScript SDK complete and compiled
✅ React hooks with React Query integration
✅ Event listener service
⏳ Frontend React app (in progress)
⏳ Wallet integration (planned)

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please ensure:

• All Move tests pass
• TypeScript compiles without errors
• Code follows existing patterns
• Add tests for new features

---

Built with ❤️ on Sui