ChatFlow Platform - Setup Guide

Prerequisite: The shared-infra stack must be running before starting ChatFlow services. It provides PostgreSQL (shared-postgres:5432, database chatflow), Redis (shared-redis:6379, DB=1), and MailHog (shared-mailhog:1025) on the shared-infra Docker network.

📋 Overview

This is the meta repository for the ChatFlow platform. It contains references to all service repositories as git submodules, along with infrastructure, documentation, and orchestration files.

🏗️ Repository Structure

ChatFlowPlatform/
├── ChatFlow/                    # ← Main platform repo (this repo)
│   ├── chatflow-identity-api/   # Auth service
│   ├── chatflow-conversation-api/ # Chat/conversation service
│   ├── chatflow-gateway-api/    # YARP API gateway
│   ├── chatflow-ai-service/     # Python AI service
│   ├── chatflow-admin-portal/   # Angular admin UI
│   ├── chatflow-user-portal/    # Angular user UI
│   ├── infrastructure/          # Database schemas, configs
│   ├── docs/                    # Platform documentation
│   ├── scripts/                 # Setup and utility scripts
│   └── docker-compose.yml       # Orchestration for all services
│
└── chatflow-sdks/               # Separate public repo → https://github.com/ChatFlowPlatform/chatflow-sdks
    ├── angular/                 # Angular SDK
    ├── react/                   # React SDK
    ├── javascript/              # Vanilla JS SDK
    ├── python/                  # Python SDK
    ├── dotnet/                  # .NET SDK
    ├── flutter/                 # Flutter SDK
    ├── swift/                   # Swift SDK
    └── widget/                  # Embeddable web widget

🚀 Quick Start

Option 1: Clone Everything (Recommended for New Users)

# Clone the platform with all submodules
git clone --recursive https://github.com/ChatFlowPlatform/chatflow-platform.git
cd chatflow-platform

# Copy environment file
cp .env.example .env
# Edit .env with your configuration

# Start all services
docker-compose up -d

Option 2: Use Existing Separate Repos

If you already have the service repos cloned separately (like your current setup):

cd chatflow-platform

# Initialize submodules to create the nested structure
git submodule update --init --recursive

# The submodules now reference the GitHub versions
# Your separate repos remain independent

🔄 Working with Submodules

Update Submodules to Latest

# Update all submodules
git submodule update --remote --merge

# Update specific submodule
git submodule update --remote --merge chatflow-identity-api

Make Changes in a Submodule

# Navigate to submodule
cd chatflow-identity-api

# Make changes, commit as normal
git add .
git commit -m "Your changes"
git push origin main

# Go back to platform repo
cd ..

# Commit the submodule reference update
git add chatflow-identity-api
git commit -m "Update identity-api submodule"
git push

Pull Latest Including Submodules

# Pull platform changes and update all submodules
git pull --recurse-submodules

🐳 Docker Compose

The docker-compose.yml file orchestrates all services:

• Infrastructure: PostgreSQL, Redis (also used as message queue via Redis Streams), Cloudflare R2 (object storage)
• Backend Services: Gateway, Auth, Chat, AI
• Monitoring: Prometheus, Grafana (optional)

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Rebuild specific service
docker-compose up -d --build auth-service

🌐 Service URLs

Once running, services are available at:

• API Gateway: http://localhost:5000
• Auth Service: http://localhost:5001
• Chat Service: http://localhost:5002
• AI Service: http://localhost:8000
• PostgreSQL: shared-postgres:5432 (via shared-infra network)
• Redis: shared-redis:6379 DB=1 (via shared-infra network)
• Cloudflare R2: managed via Cloudflare dashboard (dash.cloudflare.com/r2)

📦 Independent Service Development

Each service can also be developed independently:

# Work on a service outside the platform repo
cd ../chatflow-identity-api
dotnet run

# Or use the submodule inside platform
cd chatflow-platform/chatflow-identity-api
dotnet run

🧪 Running Tests

# Test from submodule
cd chatflow-platform/chatflow-identity-api/tests
dotnet test

# Test from standalone repo
cd ../chatflow-identity-api/tests
dotnet test

🔐 Environment Variables

Copy .env.example to .env and configure:

# Shared infrastructure credentials (must match shared-infra stack)
POSTGRES_PASSWORD=changeme123
REDIS_PASSWORD=changeme

# JWT
JWT_SECRET=your-super-secret-jwt-key-min-32-chars

# AI Services
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

📚 Documentation

• README.md - Platform overview
• ARCHITECTURE.md - System architecture
• CONTRIBUTING.md - Contribution guidelines
• QUICKSTART.md - Quick start guide

🤝 Contributing

1. Each service repository has its own contribution guidelines
2. For infrastructure/platform-wide changes, create PRs to this repo
3. Service-specific changes go to individual service repos

🆘 Common Issues

Submodules are empty

git submodule update --init --recursive

Submodule detached HEAD

cd chatflow-identity-api
git checkout main
cd ..

Update submodule to specific commit

cd chatflow-identity-api
git checkout <commit-hash>
cd ..
git add chatflow-identity-api
git commit -m "Update submodule to specific version"

🎯 Key Benefits of This Setup

✅ Centralized Overview - Clone one repo to get everything
✅ Independent Development - Each service has its own repo
✅ Version Control - Platform repo tracks specific submodule versions
✅ Easy Orchestration - Single docker-compose for entire stack
✅ Flexible Deployment - Deploy individual services or full platform

---

Need help? Check individual service READMEs or open an issue on GitHub.