ColaFlow/README.md

# ColaFlow

**AI-powered Project Management System based on MCP Protocol**

ColaFlow is a next-generation project management platform inspired by Jira's agile methodology, enhanced with AI capabilities and built on the Model Context Protocol (MCP). It enables AI agents to securely read and write project data, generate documentation, sync progress, and create comprehensive reports.

---

## Quick Start (Docker)

### Prerequisites

- **Docker Desktop** (latest version)
- **8GB RAM** (recommended)
- **10GB disk space**

### Start Development Environment

**Windows (PowerShell):**
```powershell
.\scripts\dev-start.ps1
```

**Linux/macOS (Bash):**
```bash
chmod +x scripts/dev-start.sh
./scripts/dev-start.sh
```

**Using npm (from colaflow-web directory):**
```bash
cd colaflow-web
npm run docker:all
```

### Access Points

- **Frontend**: http://localhost:3000
- **Backend API**: http://localhost:5000
- **Swagger UI**: http://localhost:5000/scalar/v1
- **PostgreSQL**: localhost:5432 (colaflow / colaflow_dev_password)
- **Redis**: localhost:6379

### Demo Accounts

See `scripts/DEMO-ACCOUNTS.md` for demo credentials:

| Role | Email | Password |
|------|-------|----------|
| Owner | owner@demo.com | Demo@123456 |
| Developer | developer@demo.com | Demo@123456 |

### Useful Commands

```powershell
# Stop all services
.\scripts\dev-start.ps1 -Stop

# View logs
.\scripts\dev-start.ps1 -Logs

# Clean rebuild
.\scripts\dev-start.ps1 -Clean

# Check status
docker-compose ps
```

---

## Manual Development

If you prefer not to use Docker:

### 1. Start PostgreSQL and Redis

```bash
# PostgreSQL
docker run -d -p 5432:5432 -e POSTGRES_DB=colaflow -e POSTGRES_USER=colaflow -e POSTGRES_PASSWORD=colaflow_dev_password postgres:16-alpine

# Redis
docker run -d -p 6379:6379 redis:7-alpine redis-server --requirepass colaflow_redis_password
```

### 2. Run Backend

```bash
cd colaflow-api
dotnet restore
dotnet ef database update
dotnet run
```

### 3. Run Frontend

```bash
cd colaflow-web
npm install
npm run dev
```

---

## Project Structure

```
product-master/
├── colaflow-api/              # Backend (.NET 9 + EF Core)
│   ├── src/
│   │   ├── ColaFlow.API/      # Main API project
│   │   ├── Modules/           # Feature modules
│   │   │   ├── Identity/      # Authentication & Authorization
│   │   │   ├── ProjectManagement/
│   │   │   └── IssueManagement/
│   │   └── Shared/            # Shared kernel
│   └── tests/
├── colaflow-web/              # Frontend (Next.js 15 + React 19)
│   ├── src/
│   │   ├── app/               # App router pages
│   │   ├── components/        # Reusable UI components
│   │   ├── lib/               # API clients and utilities
│   │   └── types/             # TypeScript type definitions
│   └── public/
├── docs/                      # Documentation
│   ├── architecture/          # Architecture Decision Records
│   ├── plans/                 # Sprint and task planning
│   └── reports/               # Status reports
├── scripts/                   # Development scripts
│   ├── dev-start.ps1          # PowerShell startup script
│   ├── dev-start.sh           # Bash startup script
│   ├── init-db.sql            # Database initialization
│   ├── seed-data.sql          # Demo data
│   └── DEMO-ACCOUNTS.md       # Demo account credentials
├── docker-compose.yml         # Docker orchestration
└── .env.example               # Environment variables template
```

---

## Technology Stack

### Backend
- **.NET 9** - Modern C# web framework
- **ASP.NET Core** - Web API framework
- **Entity Framework Core** - ORM for database access
- **PostgreSQL 16** - Relational database
- **Redis 7** - Caching and session storage
- **MediatR** - CQRS and mediator pattern
- **FluentValidation** - Input validation
- **SignalR** - Real-time communication

### Frontend
- **Next.js 15** - React framework with App Router
- **React 19** - UI library
- **TypeScript** - Type-safe JavaScript
- **Tailwind CSS** - Utility-first CSS framework
- **shadcn/ui** - Component library
- **TanStack Query** - Data fetching and caching
- **Zustand** - State management

### Infrastructure
- **Docker** - Containerization
- **Docker Compose** - Multi-container orchestration

---

## Features

### Core Features (M1)
- ✅ Multi-tenant architecture
- ✅ User authentication and authorization (JWT)
- ✅ Project management (Create, Read, Update, Delete)
- ✅ Epic, Story, Task hierarchy
- ✅ Real-time notifications (SignalR)
- ✅ Role-based access control (RBAC)
- ✅ Cross-tenant security

### Planned Features (M2)
- 🚧 MCP Server integration
- 🚧 AI-powered task generation
- 🚧 Intelligent project insights
- 🚧 Automated documentation
- 🚧 Progress reporting

---

## Development Workflow

### Daily Development

1. **Start backend services** (if not already running):
   ```bash
   docker-compose up -d postgres redis backend
   ```

2. **Run frontend locally** (for hot reload):
   ```bash
   cd colaflow-web
   npm run dev
   ```

3. **View logs**:
   ```bash
   docker-compose logs -f backend
   ```

4. **Stop services**:
   ```bash
   docker-compose down
   ```

### Database Migrations

```bash
# Create new migration
cd colaflow-api/src/ColaFlow.API
dotnet ef migrations add MigrationName

# Apply migrations
dotnet ef database update

# Rollback migration
dotnet ef database update PreviousMigrationName
```

### Testing

```bash
# Backend tests
cd colaflow-api
dotnet test

# Frontend tests
cd colaflow-web
npm test
```

---

## Documentation

- **Architecture**: [docs/architecture/](docs/architecture/)
- **Sprint Planning**: [docs/plans/](docs/plans/)
- **Docker Setup**: [docs/DOCKER-DEVELOPMENT-ENVIRONMENT.md](docs/DOCKER-DEVELOPMENT-ENVIRONMENT.md)
- **Demo Accounts**: [scripts/DEMO-ACCOUNTS.md](scripts/DEMO-ACCOUNTS.md)

---

## Troubleshooting

### Container won't start

```bash
# View detailed logs
docker-compose logs backend

# Check port conflicts
netstat -ano | findstr :5000

# Force rebuild
docker-compose up -d --build --force-recreate
```

### Database connection fails

```bash
# Check PostgreSQL health
docker-compose ps postgres

# View PostgreSQL logs
docker-compose logs postgres

# Restart PostgreSQL
docker-compose restart postgres
```

### Frontend can't connect to backend

1. Verify `.env.local` has correct `NEXT_PUBLIC_API_URL`
2. Check backend health: `docker-compose ps backend`
3. Review CORS logs: `docker-compose logs backend | grep CORS`

### Hot reload not working

```bash
# Verify volume mounts
docker-compose config | grep -A 5 "frontend.*volumes"

# Restart frontend
docker-compose restart frontend
```

---

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## License

This project is proprietary software. All rights reserved.

---

## Support

For issues, questions, or contributions:

- **Documentation**: Check `docs/` directory
- **Docker Logs**: Run `docker-compose logs`
- **Contact**: Open an issue on GitHub

---

**Version**: 1.0.0
**Last Updated**: 2025-11-04
**Maintained by**: ColaFlow Development Team