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):

.\scripts\dev-start.ps1

Linux/macOS (Bash):

chmod +x scripts/dev-start.sh
./scripts/dev-start.sh

Using npm (from colaflow-web directory):

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

# 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

# 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

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

3. Run Frontend

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):

   docker-compose up -d postgres redis backend
   

2. Run frontend locally (for hot reload):

   cd colaflow-web
   npm run dev
   

3. View logs:

   docker-compose logs -f backend
   

4. Stop services:

   docker-compose down
   

Database Migrations

# 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

# Backend tests
cd colaflow-api
dotnet test

# Frontend tests
cd colaflow-web
npm test

---

Documentation

• Architecture: docs/architecture/
• Sprint Planning: docs/plans/
• Docker Setup: docs/DOCKER-DEVELOPMENT-ENVIRONMENT.md
• Demo Accounts: scripts/DEMO-ACCOUNTS.md

---

Troubleshooting

Container won't start

# 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

# 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

# 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