SyncSpace - AI-Powered Task Platform

Manager assigns a task -> AI Orchestrator decomposes it -> Specialist Agents execute -> Report returned.

Architecture

syncspace/
├── frontend/   React + Vite + Tailwind
├── backend/    Node.js + Express + MongoDB + Socket.IO
└── ai/         Python + FastAPI + HuggingFace Inference API

Run Without Docker

This project can run without Docker. Docker is not required for local development.

Required

• Node.js 18+
• Python 3.11+
• MongoDB Atlas URI or local MongoDB
• HuggingFace API key

Optional

• Redis URL, only needed when real queue/status persistence is added. The current task flow does not depend on Redis.
• LangGraph, recommended later if the AI agent workflow needs durable graph state, branching, retries, human review steps, or resumable execution.

Environment Setup

The app uses separate env files:

backend\.env
ai\.env
frontend\.env

Important values:

MONGO_URI=mongodb+srv://user:password@cluster.mongodb.net/syncspace?retryWrites=true&w=majority
AI_SERVICE_URL=http://localhost:8000
BACKEND_URL=http://localhost:3000
FRONTEND_URL=http://localhost:5173
INTERNAL_WEBHOOK_SECRET=use_the_same_value_in_backend_and_ai
HUGGINGFACE_API_KEY=hf_your_key_here

The backend and AI service both support MONGO_URI. Keep INTERNAL_WEBHOOK_SECRET identical in backend/.env and ai/.env.

Install And Start

1. Backend

cd backend
npm install
npm run dev

Runs on http://localhost:3000.

2. AI Service

Open a new terminal:

cd ai
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py

Runs on http://localhost:8000.

3. Frontend

Open a new terminal:

cd frontend
npm install
npm run dev

Runs on http://localhost:5173.

Health Checks

Invoke-RestMethod http://localhost:3000/health
Invoke-RestMethod http://localhost:8000/health

Then open http://localhost:5173.

Core Flow

1. Manager creates a task on the dashboard.
2. Backend saves it to MongoDB and calls the Python AI service.
3. AI orchestrator uses HuggingFace to split the task into subtasks.
4. Specialist agents execute each subtask.
5. AI sends protected internal webhook updates back to the backend.
6. Socket.IO broadcasts live progress to the browser.
7. Final report is saved and linked to the original user task.

API Endpoints

Backend

Method	Path	Description
POST	/api/v1/auth/register	Register
POST	/api/v1/auth/login	Login
GET	/api/v1/auth/profile	Get profile
POST	/api/v1/tasks	Create and queue task
GET	/api/v1/tasks	List user tasks
GET	/api/v1/tasks/stats	Dashboard stats
GET	/api/v1/tasks/:id	Task and subtasks
DELETE	/api/v1/tasks/:id	Delete task
POST	/api/v1/tasks/:taskId/subtask-update	Internal AI webhook
GET	/api/v1/reports	List user reports
GET	/api/v1/reports/task/:taskId	Report by task
GET	/api/v1/reports/:id	Report detail
POST	/api/v1/reports/task/:taskId/save	Internal AI webhook

AI Service

Method	Path	Description
GET	/health	Health check
POST	/api/tasks/process	Start AI processing
GET	/api/tasks/:taskId/status	Processing status

Socket Events

Event	Direction	Description
join:task	Client -> Server	Subscribe to task updates
task:queued	Server -> Client	Task accepted
task:processing	Server -> Client	Orchestrator started
task:progress	Server -> Client	Progress update
task:completed	Server -> Client	All agents done
task:failed	Server -> Client	Error occurred
subtask:completed	Server -> Client	Single agent done
report:ready	Server -> Client	Report available

Notes

• Docker compose is currently optional and not the main path.
• Rotate any database/API credentials that were shared publicly or committed accidentally.
• Redis and LangGraph are good next upgrades, but the current MVP can run without them.