ColaFlow Web

AI-Powered Project Management System - Frontend

Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript 5.x
• UI Components: shadcn/ui + Radix UI
• Styling: Tailwind CSS 4
• State Management:
  • TanStack Query v5 (server state)
  • Zustand (client state)
• Form Handling: React Hook Form + Zod
• Icons: Lucide React

Project Structure

colaflow-web/
├── app/                    # Next.js App Router
│   ├── (auth)/            # Authentication routes
│   ├── (dashboard)/       # Main application routes
│   │   ├── dashboard/     # Dashboard page
│   │   ├── projects/      # Projects management
│   │   └── kanban/        # Kanban board
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Home page (redirects to dashboard)
├── components/
│   ├── ui/                # shadcn/ui components
│   ├── features/          # Feature-specific components
│   │   ├── projects/      # Project components
│   │   └── kanban/        # Kanban components
│   └── layout/            # Layout components (Header, Sidebar)
├── lib/
│   ├── api/              # API client and endpoints
│   ├── hooks/            # Custom React hooks
│   ├── providers/        # Context providers
│   └── utils.ts          # Utility functions
├── stores/               # Zustand stores
├── types/                # TypeScript type definitions
└── public/               # Static assets

Getting Started

Prerequisites

• Node.js 20 LTS or higher
• npm or yarn

Installation

1. Install dependencies:

npm install

2. Create .env.local file:

NEXT_PUBLIC_API_URL=http://localhost:5000/api/v1

Development

Start the development server:

npm run dev

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

Build

Build the production application:

npm run build

Linting & Formatting

# Run ESLint
npm run lint

# Format code with Prettier
npm run format

# Check formatting without modifying files
npm run format:check

Code Quality Standards

TypeScript

• Strict Mode: Enabled in tsconfig.json
• No any Types: Prohibited by ESLint (@typescript-eslint/no-explicit-any: error)
• Type Definitions: All components, functions, and API responses must have proper type definitions
• Type Safety: Prefer discriminated unions over type assertions

Linting

• ESLint: Configured with TypeScript and React rules
• Next.js Rules: Extended from eslint-config-next
• Accessibility: Enforced via eslint-plugin-jsx-a11y
• Run: npm run lint

Code Formatting

• Prettier: Configured for consistent code formatting
• Tailwind Plugin: Automatic class sorting via prettier-plugin-tailwindcss
• Configuration: See .prettierrc
• Run: npm run format
• Check: npm run format:check

Pre-commit Hooks

Husky automatically runs checks before each commit:

1. TypeScript Compilation Check - npx tsc --noEmit
2. ESLint + Prettier - Via lint-staged (only on staged files)

If any check fails, the commit will be blocked. Fix the issues before committing.

Development Workflow

1. Make Changes: Edit your code
2. Format Code: Run npm run format (or let your IDE auto-format)
3. Check Linting: Run npm run lint to check for issues
4. Commit: Run git commit (hooks will run automatically)
   • TypeScript check runs on all files
   • ESLint + Prettier run only on staged files (fast)
5. Fix Issues: If hooks fail, fix the issues and try again

Bypassing Hooks (Emergency Only)

Only bypass hooks in emergency situations:

git commit --no-verify -m "Emergency fix"

Use this sparingly - it's better to fix the issues properly.

VS Code Settings (Recommended)

Add to .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Features Implemented (Sprint 1)

Core Pages

• Dashboard with project overview
• Projects list page with search and filtering
• Project detail page
• Kanban board (static, drag-and-drop in Sprint 2)

Components

• Responsive layout with sidebar navigation
• Project creation dialog with form validation
• Kanban board with column and task cards
• shadcn/ui integration (Button, Card, Dialog, Form, Input, Table)

State Management

• TanStack Query for server state
• Zustand for UI state (sidebar, theme, modals, notifications)
• Custom hooks for projects and kanban

API Integration

• Type-safe API client with error handling
• Projects API endpoints
• Kanban board API integration

TypeScript Types

All API responses and data models are fully typed:

• types/project.ts - Project, Epic, Story, Task types
• types/kanban.ts - Kanban board types
• types/user.ts - User and authentication types

API Endpoints

The frontend expects the following API endpoints:

• GET /api/v1/projects - List all projects
• POST /api/v1/projects - Create project
• GET /api/v1/projects/{id} - Get project details
• PUT /api/v1/projects/{id} - Update project
• DELETE /api/v1/projects/{id} - Delete project
• GET /api/v1/projects/{id}/kanban - Get kanban board

Environment Variables

Variable	Description	Default
NEXT_PUBLIC_API_URL	Backend API URL	http://localhost:5000/api/v1

Next Steps (Sprint 2)

• Implement drag-and-drop for Kanban board
• Add task creation and editing
• Implement authentication (login/register)
• Add user profile management
• Implement real-time updates with SignalR
• Add workflow customization
• Implement audit logs viewer

Architecture Reference

For complete architecture details, see: docs/M1-Architecture-Design.md

License

Proprietary - ColaFlow Project