AI4MDE Chatbot System

An AI-powered requirements engineering system that uses intelligent agents to conduct interviews, generate documentation, and create UML diagrams for software projects.

🏗️ Architecture Overview

This system follows a microservices architecture with domain-driven design principles:

chatbot/
├── chatback/         # Backend API service (FastAPI + LangGraph)
├── chatfront/        # Frontend application (Remix + React)
├── genpdf/           # PDF generation service
├── plantuml/         # PlantUML diagram service
├── d2/               # D2 diagram service
├── config/           # Centralized configuration
└── compose.yml       # Container orchestration

System Architecture Diagram

graph TB
    subgraph "User Layer"
        User[👤 User/Browser]
    end

    subgraph "Reverse Proxy Layer"
        Traefik[Traefik<br/>Local Development]
        Cloudflare[Cloudflare Tunnel<br/>Production]
    end

    subgraph "Frontend Layer"
        ChatFront[ChatFront<br/>Remix + React<br/>Port 3000]
    end

    subgraph "Backend Layer"
        ChatBack[ChatBack<br/>FastAPI + LangGraph<br/>Port 8000]
    end

    subgraph "Microservices Layer"
        GenPDF[GenPDF<br/>Pandoc + XeLaTeX<br/>Port 8010]
        PlantUML[PlantUML<br/>Java Server<br/>Port 8020]
        D2[D2 Diagrams<br/>D2 Renderer<br/>Port 8030]
    end

    subgraph "Data Layer"
        Postgres[(PostgreSQL<br/>User & Chat Data)]
        Redis[(Redis<br/>Cache & Sessions)]
        Qdrant[(Qdrant<br/>Vector Search)]
    end

    subgraph "External Services"
        OpenAI[OpenAI API<br/>GPT-4 Models]
        Studio[AI4MDE Studio<br/>Diagram Export/Import]
    end

    %% User connections
    User -.->|HTTP/HTTPS<br/>Optional| Traefik
    User -->|HTTPS| Cloudflare

    %% Reverse proxy connections (Traefik is optional for local dev)
    Traefik -.->|ai4mde.localhost| ChatFront
    Traefik -.->|ai4mde.api.localhost| ChatBack
    Cloudflare -->|Secure Tunnel| ChatFront
    Cloudflare -->|Secure Tunnel| ChatBack

    %% Frontend to Backend
    ChatFront -->|REST API<br/>WebSocket| ChatBack

    %% Backend to Microservices
    ChatBack -->|Generate PDF| GenPDF
    ChatBack -->|Render Diagrams| PlantUML
    ChatBack -->|Render D2| D2

    %% Backend to Data Layer
    ChatBack -->|SQL Queries| Postgres
    ChatBack -->|Cache/Sessions| Redis
    ChatBack -->|Vector Search| Qdrant

    %% Backend to External Services
    ChatBack -->|LangGraph Agents| OpenAI
    ChatBack -->|Export/Import<br/>Diagrams| Studio

    %% Styling
    classDef frontend fill:#61dafb,stroke:#333,stroke-width:2px,color:#000
    classDef backend fill:#009688,stroke:#333,stroke-width:2px,color:#fff
    classDef service fill:#ff9800,stroke:#333,stroke-width:2px,color:#000
    classDef data fill:#9c27b0,stroke:#333,stroke-width:2px,color:#fff
    classDef openai fill:#10a37f,stroke:#333,stroke-width:2px,color:#fff
    classDef studio fill:#2196f3,stroke:#333,stroke-width:2px,color:#fff
    classDef proxy fill:#607d8b,stroke:#333,stroke-width:2px,color:#fff
    classDef proxyOptional fill:#b0bec5,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5,color:#000

    class ChatFront frontend
    class ChatBack backend
    class GenPDF,PlantUML,D2 service
    class Postgres,Redis,Qdrant data
    class OpenAI openai
    class Studio studio
    class Traefik proxyOptional
    class Cloudflare proxy

Loading

Main Services:

• ChatBack - Backend API service with AI agents (FastAPI + LangGraph) - README
• ChatFront - Frontend web application (Remix + React) - README
• GenPDF - PDF generation service (Pandoc + XeLaTeX + Eisvogel) - README
• PlantUML - UML diagram rendering service (Java-based) - README
• D2 - D2 diagram rendering service (Modern declarative diagrams) - README

Data Stores:

• PostgreSQL - Primary database for users, sessions, and content
• Redis - Caching and session management
• Qdrant - Vector database for semantic search

External Services:

• OpenAI API - AI model provider (GPT-4)
• AI4MDE Studio - Diagram management integration

🚀 Quick Start

Prerequisites

• Podman (or Docker)
• Podman Compose (or Docker Compose)
• OpenAI API key
• 8GB+ RAM recommended

1. Clone and Setup

git clone https://github.com/ai4mde/chatbot.git
cd chatbot

2. Configure Environment

# Copy environment templates
cp config/chatback.env.example config/chatback-dev.env
cp config/chatfront.env.example config/chatfront-dev.env

# Edit config/chatback-dev.env and configure:
# - OPENAI_API_KEY: Your OpenAI API key (REQUIRED)
# - ADMIN_USERNAME: Admin username (default: admin)
# - ADMIN_PASSWORD: Admin password (REQUIRED - set a strong password)
# - DATABASE_URL: PostgreSQL connection
# - REDIS_URL: Redis connection
# - SECRET_KEY: JWT secret
# - JWT_SECRET_KEY: JWT signing secret

# Edit config/chatfront-dev.env and configure:
# - SESSION_SECRET: Session encryption key
# - API_URL: Backend API URL (default: http://chatback:8000)

# Available environment files:
# - chatback-dev.env / chatfront-dev.env (development)
# - chatback-prd.env / chatfront-prd.env (production)

3. Setup Data Directory

The application requires a persistent data directory for storing generated documents, interviews, and diagrams.

Note: Replace {version-number} with the actual version (e.g., version 0.7.9 becomes 079).

# Set version number
version_number=079

# Create data directory (version-specific)
doas mkdir -p /opt/ai4mde/$version_number/data

# Copy the data template structure
doas cp -r data-template/* /opt/ai4mde/$version_number/data

# Set appropriate permissions
doas chown -R 1101:1101 /opt/ai4mde/$version_number

Data directory structure:

• templates/ - Document templates
  • srsdoc_template.md - IEEE 830-compliant SRS document template
  • technical_doc_template.md - Technical documentation template
• questionnaires/ - Interview question sets for AI agents
  • interview_questions.md - Comprehensive requirements gathering questions
  • evaluation.md - Post-experience evaluation survey
  • onboarding.md - Professional onboarding assessment
• <test-group>/ - Example group directory structure (replicated per user group):
  • diagrams/ - Generated UML diagrams (PlantUML/D2 formats)
  • interviews/ - Stored interview transcripts
  • requirements/ - Extracted requirements documents
  • srsdocs/ - Generated SRS documents (Markdown/PDF)
• output/ - System-generated evaluation and onboarding results
• workflow/ - Workflow progress tracking (JSON state files)

Note: Each user group will have its own subdirectory (like <test-group>/) created automatically when users interact with the system. The version-specific directory structure allows running multiple versions simultaneously.

4. Build and Start Services

# Build all services
podman compose -f compose.yml build

# Build and Start all services
podman compose -f compose.yml up -d

# Or start specific services
podman compose -f compose.yml up -d postgres redis qdrant  # Data layer
podman compose -f compose.yml up -d chatback               # Backend
podman compose -f compose.yml up -d chatfront              # Frontend

5. Access the Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• PDF Service: http://localhost:8010
• PlantUML Service: http://localhost:8020
• D2 Service: http://localhost:8030

👥 Login and Create Users and Groups:

The system creates a default admin account on first startup. The credentials are configured in your environment file (config/chatback-dev.env or config/chatback-prd.env):

• Username: Value of ADMIN_USERNAME (default: admin)
• Password: Value of ADMIN_PASSWORD (set in your env file)

To create users and groups:

1. Navigate to http://localhost:3000 and log in with the admin credentials
2. Go to the Admin Dashboard (accessible from the navigation menu or at /admin)
3. Create groups for organizing users (e.g., "project-team-1", "research-group-a")
4. Create users and assign them to groups

Why Users and Groups Matter:

Users and groups are essential for collaboration:

• Shared Workspace: Users in the same group can see each other's work, interviews, and generated documents
• Collaboration: Team members can review and build upon each other's requirements and diagrams
• Data Organization: Each group has its own dedicated directory structure for interviews, requirements, and diagrams

📹 Video Tutorial

For a complete walkthrough of the system setup and usage, view the video tutorial:

🎬 View Video Tutorial

This tutorial covers:

• Initial setup and configuration
• Admin dashboard and user management
• Creating users and groups
• Conducting AI-powered interviews
• Generating requirements documents and UML diagrams
• Export the diagrams to AI4MDE Studio
• Show and modify the diagrams in AI4MDE Studio

🎯 Core Features

• AI-Powered Interviews - Intelligent requirements gathering through conversational AI
• Document Generation - Automatic SRS generation with professional PDF output
• UML Diagram Creation - Class, sequence, activity, and use case diagrams
• Workflow Management - Guided project workflow with progress tracking

📚 Documentation:

• ChatBack README - Backend API, AI agents, and LangGraph workflows
• ChatFront README - Frontend application and user interface
• GenPDF README - PDF generation service
• PlantUML README - UML diagram rendering
• D2 README - D2 diagram rendering
• DEVELOPMENT.md - Development, deployment, and troubleshooting
• ALIASES.md - Podman Compose command aliases

📄 License

See LICENSE file for details.

---

Version: 0.7.9 Last Updated: October 2024 Project: AI4MDE - AI for Model-Driven Engineering