Skip to content

chatback

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

chatback

README.md

ChatBack - AI Requirements Engineering Backend

FastAPI-based backend service for the AI4MDE chatbot system, featuring intelligent agents for requirements gathering, document generation, and UML diagram creation.

Overview

ChatBack is a sophisticated backend API service that orchestrates AI agents using LangGraph to:

  • Conduct intelligent stakeholder interviews
  • Generate IEEE-compliant SRS documents
  • Create and manage UML diagrams
  • Manage user sessions and authentication
  • Coordinate microservices (PDF generation, PlantUML rendering)

Architecture

Domain-Driven Design Structure

chatback/app/
├── api/                    # REST API Layer
│   ├── v1/
│   │   ├── endpoints/     # API endpoints
│   │   │   ├── admin.py          # Admin & user management
│   │   │   ├── auth.py           # Authentication
│   │   │   ├── chat.py           # Main chat interface
│   │   │   ├── message_routes.py # Message management
│   │   │   ├── search_routes.py  # Search functionality
│   │   │   ├── session_routes.py # Session management
│   │   │   ├── srs_chat.py       # SRS document chat
│   │   │   └── studio.py         # Studio integrations
│   │   └── api.py         # Router aggregation
│   └── deps.py            # Dependency injection
│
├── core/                  # Core Infrastructure
│   ├── agents/           # Agent framework
│   │   ├── base.py              # Base agent classes
│   │   ├── decorators.py        # Agent decorators
│   │   ├── exceptions.py        # Agent exceptions
│   │   ├── monitoring.py        # Agent monitoring
│   │   ├── retry.py             # Retry logic
│   │   └── types.py             # Type definitions
│   ├── services/         # Core services
│   │   ├── session_document_mapper.py
│   │   └── studio_converters.py
│   ├── auth.py           # Authentication utilities
│   ├── config_manager.py # Configuration management
│   ├── logging_config.py # Logging configuration
│   ├── path_utils.py     # Path utilities
│   ├── security.py       # Security utilities
│   └── version.py        # Version management
│
├── crud/                  # Database Operations
│   ├── base.py           # Base CRUD
│   ├── crud_chat.py      # Chat CRUD
│   ├── crud_group.py     # Group CRUD
│   └── crud_user.py      # User CRUD
│
├── domain/               # Business Logic Layer
│   ├── chat/            # Chat Domain
│   │   ├── chat_manager.py              # Chat orchestration
│   │   ├── chat_manager_factory.py      # Factory pattern
│   │   ├── documentation_processor.py   # Document processing
│   │   ├── errors.py                    # Domain errors
│   │   ├── message_handler.py           # Message handling
│   │   ├── openai_service.py            # OpenAI integration
│   │   ├── requirements.py              # Requirements processing
│   │   ├── session_manager.py           # Session management
│   │   ├── srs_chat_service.py          # SRS chat service
│   │   ├── templates/                   # Jinja2 templates
│   │   └── utils/                       # Chat utilities
│   │
│   ├── diagrams/        # Diagram Generation Domain
│   │   ├── diagram_agent.py             # Main diagram agent
│   │   ├── diagram_agent_factory.py     # Agent factory
│   │   ├── diagram_generation_engine.py # Generation engine
│   │   ├── diagram_prompt_manager.py    # Prompt management
│   │   ├── diagram_state_manager.py     # State management
│   │   ├── plantuml_sanitizer.py        # PlantUML sanitization
│   │   ├── save_diagrams.py             # Diagram persistence
│   │   ├── uml_api_client.py            # External UML APIs
│   │   ├── uml_converter_agent.py       # UML conversion
│   │   ├── uml_diagram_operations.py    # Diagram operations
│   │   └── uml_parser.py                # PlantUML parsing
│   │
│   ├── documents/       # Document Generation Domain
│   │   ├── document_agent.py            # Base document agent
│   │   ├── document_coordinator.py      # Document coordination
│   │   ├── document_reviewer_agent.py   # Review agent
│   │   ├── document_writer_agent.py     # Writer agent
│   │   ├── modification_agent.py        # Modification agent
│   │   ├── srs_document_agent.py        # SRS agent
│   │   ├── utils.py                     # Document utilities
│   │   └── prompts/                     # Agent prompts
│   │
│   ├── interviews/      # Interview Domain
│   │   └── interview/
│   │       ├── interview_agent.py           # Interview agent
│   │       ├── interview_agent_factory.py   # Factory
│   │       ├── interview_message_processor.py # Message processor
│   │       ├── interview_state_manager.py   # State manager
│   │       ├── question_loader.py           # Question loading
│   │       └── save_interview.py            # Interview persistence
│   │
│   └── prompts/         # Domain Prompts
│       ├── diagram_agent_prompt.yaml
│       ├── enhanced_diagram_prompts.yaml
│       ├── interview_prompt.yaml
│       ├── srs_agent_prompt.yaml
│       ├── srs_chat_prompts.yaml
│       ├── thompson_agent_prompt.yaml
│       └── themes/                      # PlantUML themes
│
├── infrastructure/      # Infrastructure Layer
│   ├── database/       # Database
│   │   ├── base_class.py    # SQLAlchemy base
│   │   ├── init_db.py       # DB initialization
│   │   └── session.py       # Session management
│   └── vectorstore/    # Vector Store
│       └── vector_store.py  # Qdrant integration
│
├── models/             # Database Models
│   ├── chat.py        # Chat models
│   ├── group.py       # Group model
│   ├── studio_export.py # Studio export model
│   └── user.py        # User model
│
├── schemas/           # Pydantic Schemas
│   ├── base_schemas.py    # Base schemas
│   ├── chat.py           # Chat schemas
│   ├── dashboard.py      # Dashboard schemas
│   ├── group.py          # Group schemas
│   ├── qdrant.py         # Vector store schemas
│   ├── srs_chat.py       # SRS chat schemas
│   ├── token.py          # Auth token schemas
│   └── user.py           # User schemas
│
└── main.py            # FastAPI application entry point

Quick Start

Prerequisites

  • Python 3.11+
  • PostgreSQL 14+
  • Redis 7+
  • Qdrant (optional, for vector search)
  • OpenAI API key
  • uv package manager

Installation

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

# Or for development with all dev dependencies
uv pip install -e ".[dev]"

Configuration

# Copy environment template
cp config/chatback.env.example config/chatback.env

# Edit config/chatback.env with required values:
# - OPENAI_API_KEY (required)
# - ADMIN_PASSWORD (required - set a strong password)
# - DATABASE_URL
# - REDIS_URL
# - SECRET_KEY

Database Setup

# Run migrations
alembic upgrade head

# The admin user will be created automatically on first startup

Run Development Server

# Using uv (recommended)
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Or using standard Python
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Or using the development script
python -m app.main

Access API Documentation

Key Features

1. Multi-Agent Architecture (LangGraph)

Intelligent agents orchestrated using LangGraph:

  • Interview Agent: Conducts stakeholder interviews with context-aware questions
  • Requirements Agent: Extracts and structures requirements
  • Diagram Agent: Generates UML diagrams (class, sequence, activity, use case)
  • Document Agent: Creates IEEE-compliant SRS documents
  • Review Agent: Reviews and refines generated content

2. Authentication & Authorization

  • JWT-based authentication
  • Role-based access control (Admin/User)
  • Secure password hashing with bcrypt
  • Session management with Redis
  • Admin dashboard for user/group management

3. Vector Search (Qdrant)

  • Semantic search across conversations
  • Similarity-based requirement matching
  • Context-aware document retrieval

4. Session Management

  • Multi-session support per user
  • Conversation history persistence
  • Session state tracking
  • Recovery and cleanup

5. Document Generation

  • Markdown-based SRS documents
  • PDF export via GenPDF service
  • PlantUML diagram integration
  • IEEE 830 compliance

6. UML Diagram Support

  • Class diagrams
  • Sequence diagrams
  • Activity diagrams
  • Use case diagrams
  • Real-time PlantUML rendering
  • Studio App integration

Development

Running Tests

# Run all tests (using uv)
uv run pytest

# Run with coverage
uv run pytest --cov=app --cov-report=html

# Run specific test file
uv run pytest tests/test_chat_manager.py

# Run integration tests
uv run pytest tests/integration/

Code Quality

# Format code (using uv)
uv run black app tests

# Sort imports
uv run isort app tests

# Type checking
uv run mypy app

# Linting
uv run ruff check app tests

Database Migrations

# Create new migration (using uv)
uv run alembic revision --autogenerate -m "Description of changes"

# Apply migrations
uv run alembic upgrade head

# Rollback migration
uv run alembic downgrade -1

# View migration history
uv run alembic history

API Endpoints

Authentication

  • POST /api/v1/auth/login - User login
  • POST /api/v1/auth/register - User registration
  • POST /api/v1/auth/refresh - Refresh JWT token

Admin

  • GET /api/v1/admin/users - List users
  • POST /api/v1/admin/users - Create user
  • PUT /api/v1/admin/users/{id} - Update user
  • DELETE /api/v1/admin/users/{id} - Delete user
  • GET /api/v1/admin/groups - List groups
  • POST /api/v1/admin/groups - Create group

Chat

  • POST /api/v1/chat/message - Send chat message
  • GET /api/v1/chat/sessions - List sessions
  • POST /api/v1/chat/sessions - Create session
  • GET /api/v1/chat/sessions/{id} - Get session details
  • DELETE /api/v1/chat/sessions/{id} - Delete session

Sessions

  • GET /api/v1/sessions - List user sessions
  • GET /api/v1/sessions/{id}/messages - Get session messages
  • GET /api/v1/sessions/{id}/files - Get session files

SRS Chat

  • POST /api/v1/srs-chat/message - Chat with SRS document
  • GET /api/v1/srs-chat/history/{doc_id} - Get SRS chat history

Search

  • GET /api/v1/search/messages - Search messages
  • GET /api/v1/search/sessions - Search sessions

Integration with Microservices

GenPDF Service (Port 8010)

# ChatBack calls GenPDF for PDF generation
async def generate_pdf(markdown_content: str):
    response = await http_client.post(
        "http://genpdf:8010/pdf/generate",
        json={"markdown": markdown_content}
    )
    return response.content

PlantUML Service (Port 8020)

# ChatBack calls PlantUML for diagram rendering
async def render_diagram(puml_code: str):
    response = await http_client.post(
        "http://plantuml:8020/diagram",
        json={"content": puml_code, "format": "svg"}
    )
    return response.content

Environment Variables

See config/chatback.env.example for all available options.

Required:

  • OPENAI_API_KEY - OpenAI API key
  • ADMIN_PASSWORD - Admin account password
  • DATABASE_URL - PostgreSQL connection string
  • REDIS_URL - Redis connection string
  • SECRET_KEY - JWT secret key

Optional:

  • ADMIN_USERNAME - Admin username (default: admin)
  • QDRANT_URL - Qdrant vector database URL
  • LOG_LEVEL - Logging level (default: INFO)
  • CORS_ORIGINS - Allowed CORS origins

Production Deployment

ChatBack is deployed as part of the complete AI4MDE system using Podman Compose. See the main README for deployment options.

Quick deployment:

# From the project root directory
cd /path/to/chatbot

# Development (direct ports)
podman compose -f compose-dev.yml up -d chatback

# Production (with Cloudflare)
podman compose up -d chatback

# Local with Traefik
podman compose -f compose-local.yml up -d chatback

The service will be built automatically using the configuration in compose.yml.

Monitoring & Health

Health Check Endpoint

curl http://localhost:8000/health

Returns:

{
  "status": "healthy",
  "version": "0.7.9",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "llm": "configured"
  }
}

Contributing

  1. Follow domain-driven design principles
  2. Write tests for new features
  3. Use type hints throughout
  4. Format code with black and isort
  5. Run pytest before committing

License

See LICENSE file in the project root for details.