ColaFlow-Web/README.md

# 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:
```bash
npm install
```

2. Create `.env.local` file:
```env
NEXT_PUBLIC_API_URL=http://localhost:5000/api/v1
```

### Development

Start the development server:

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser.

### Build

Build the production application:

```bash
npm run build
```

### Linting & Formatting

```bash
# 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:

```bash
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`:

```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