Sync Flow

Sync anything, anywhere, with anyone.

Sync Flow is a high-performance, real-time collaboration workspace built for issue tracking, agile sprint management, and instant team communication.

---

Features

• Agile Kanban Board & Planning Views: Drag-and-drop board layouts with optimistic ordering, interactive sprint backlogs, status columns, and timeline progress rails.
• Real-time Communication Channels: Instant messaging channels and live workspace notification alerts powered by Socket.IO sockets.
• Live Video & Audio Calls: WebRTC channel calls powered by LiveKit Cloud integration, featuring persistent global call state, floating overlay widgets, participant menus, and fullscreen view.
• Native Localization Support: Built-in multi-locale gated routing for English (en) and Vietnamese (vi) powered by next-intl.
• Hybrid Auth Security Model: Protected routes, WebSocket channels, and video call tokens secured via HttpOnly session cookies (session_token).
• Sleek Workspace Navigation: Expandable sidebars, active workspace rails, collapsible sublists, and zinc-scale responsive panels.
• Zero-Manual-Memoization Architecture: Leverages the React Compiler to automatically optimize component rendering performance without manual useMemo or useCallback hooks.

---

Technology Stack

Category	Technology / Library	Version	Description
Framework	Next.js (App Router)	16.2.9	React framework with server rendering & routing
UI Library	React + React Compiler	19.2.3	UI library with native auto-memoization enabled
State Management	TanStack React Query	^5.90.20	Server state caching, invalidation, & query factories
Client UI State	Zustand	^5.0.11	Persisted client UI state management
Realtime Video Calls	LiveKit WebRTC	^2.21.0	Cloud WebRTC video & audio call sessions
Styling & Motion	Tailwind CSS & Framer Motion	^4.0.0 / ^12.40.0	Modern CSS utilities and fluid UI animations
Form Handling	@tanstack/react-form & Zod	^1.28.0 / ^4.3.6	Type-safe form state & validation
Realtime WebSockets	Socket.IO Client	^4.8.1	Socket connections for chat & notification feeds
Internationalization	next-intl	^4.8.2	Internationalized routing and translation bundles
Test Runner	Vitest	^4.1.9	Modern unit & integration test runner

Note

This repository contains the Frontend codebase. The corresponding Backend service code is maintained in the adjacent be/ workspace.

---

Getting Started

Prerequisites

• Node.js v18+ (tested on v24.12.0)
• pnpm package manager
• Running Sync Flow backend service instance (defaults to http://localhost:8000)

Installation & Local Setup

1. Clone the repository and enter the frontend workspace:

   cd sync-flow/fe

2. Install project dependencies:

   pnpm install

3. Configure local environment variables:

   cp .env.example .env.local

4. Launch the local development server:

   pnpm dev

   Open http://localhost:3000 in your browser.

---

Quality Assurance & Verification

Maintain code quality, linting standards, and compiler optimization rules with standard repository commands:

pnpm lint     # Run ESLint static analysis
pnpm test     # Run Vitest unit & integration tests
pnpm doctor   # Run React Doctor codebase diagnostic audit
pnpm build    # Execute production Next.js compilation

Tip

React Compiler & Memoization Policy: React Compiler automatically analyzes components and memoizes calculations at build time. Manual memoization hooks (useMemo, useCallback, and memo()) are unnecessary and flagged by static analysis (pnpm doctor). Keep UI components purely presentational and avoid manual memoization wrappers.

---

Directory Structure

app/                      # Next.js App Router route tree & layout providers
components/               # UI components categorized by feature domain
  ├── auth/               # Animated auth card layouts and background animations
  ├── call/               # LiveKit video/audio call provider, floating widget, & overlay
  ├── canvas/             # Board (Kanban), Backlog table, Planning, & Timeline rails
  ├── channel/            # Channel header call controls & action buttons
  ├── dashboard/          # Chat channels, notification menus, and shell layouts
  │   ├── chat/           # Message list, composer, and useComposer hook
  │   ├── comp/           # Dialogs (includes modular issue-detail dialog)
  │   └── layout/         # Shell sidebars (includes navigation-sidebar module)
  ├── shared/             # Shared UI widgets and layout animations
  └── ui/                 # Atomic design system tokens and Radix/shadcn primitives
hooks/                    # Custom application hooks and TanStack mutation wrappers
i18n/                     # Modular translation message bundles (en/vi) and routing
lib/                      # API client transport, Zustand stores, and ordering helpers
queries/                  # TanStack Query keys and option factories
types/                    # Application TypeScript interface declarations
docs/codebase/            # Structured repository documentation suite

---

Architecture Overview

[Browser Client]
       │
       ▼ (Validates cookies & locale)
  [proxy.ts Middleware]
       │
       ▼ (Bootstraps layout context & providers)
  [app/[locale]/layout.tsx]
       │
       ├─► [queries/*] ───────► (React Query data fetching) ─► [lib/api/api-config.ts] ─► [/api-proxy Rewrite] ─► [Backend API]
       ├─► [hooks/mutations] ─► (Optimistic UI updates) ─────► [lib/api/api-config.ts] ─► [/api-proxy Rewrite] ─► [Backend API]
       └─► [lib/api/chat] ────► (Real-time WebSockets) ──────► [lib/api/api-config.ts] ──────────────────────► [Backend WebSockets]

• Authentication & Gated Routes: Managed via proxy.ts middleware, verifying the HttpOnly session_token cookie and applying locale redirects.
• Real-time WebSockets: WebSockets for /chat and /notifications authenticate using the client's session_token cookie.
• Sparse Board Reordering: Drag-and-drop operations compute midpoint values using lib/ordering.ts helpers. Rapid reorders run optimistically through flush-and-sequence queue hooks (useColumnReorder, useIssueMove).
• Presenter/Hook Pattern: Complex components separate UI layout from state logic via dedicated custom hooks (useNavigationSidebar, useIssueDetail, useComposer).
• Centralized API Proxying: API endpoints resolve dynamically in lib/api/api-config.ts using client relative /api-proxy rewrites to prevent direct backend URL hardcoding.

---

Codebase Documentation Index

Detailed architectural specs and integration maps are maintained in docs/codebase/:

• STACK.md — Tech stack, framework versions, dev tooling, and scripts.
• STRUCTURE.md — Directory topology, entry points, and module boundaries.
• ARCHITECTURE.md — System flow, layers, reordering strategies, and risks.
• CONVENTIONS.md — Naming rules, error handling, query factories, and Compiler rules.
• INTEGRATIONS.md — Backend API rewrites, cookies, WebSockets, and data stores.
• TESTING.md — Vitest test patterns, setup configs, and quality assurance commands.
• CONCERNS.md — High-churn file analysis, technical debt tracking, and security notes.