Conversation Model Documentation

Overview

The Conversation model represents exported AI conversation sessions in the CODITECT platform. It serves as a knowledge management system, capturing interactions between users and AI agents for future reference, learning, and compliance. The model tracks metadata about conversations while the actual message content is stored in external files, enabling efficient indexing and searchability.

Model Structure

Core Fields

Field	Type	Description	Constraints
id	UUID	Unique conversation identifier	Primary key, auto-generated
tenant_id	UUID	Associated tenant	Foreign key to Tenant
user_id	UUID	User who had conversation	Foreign key to User
session_id	String	Original session identifier	Required, for correlation
ai_provider	String	AI provider used	Required (e.g., "claude", "gemini")
title	String	Conversation title	Required, auto-generated or user-set
description	String (Optional)	Summary or context	User-provided
tags	Vec	Categorization tags	For filtering and search
filename	String	Export file name	Required
path	String	Storage path	Required (e.g., GCS path)
status	ConversationStatus (Enum)	Current status	Required
created_at	DateTime	Conversation start time	Auto-set
updated_at	DateTime	Last modification	Auto-updated
message_count	u32 (Optional)	Number of messages	For quick reference
token_count	u32 (Optional)	Total tokens used	For cost tracking

ConversationStatus Enum

enum ConversationStatus {
    Active,    // Currently accessible
    Archived,  // Moved to cold storage
    Deleted    // Soft deleted
}

Example Structures

Development Conversation

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "456e7890-e89b-12d3-a456-426614174000",
  "session_id": "session-2025-08-29-14-30-00",
  "ai_provider": "claude",
  "title": "Implement OAuth2 Authentication",
  "description": "Designed and implemented OAuth2 flow with refresh tokens",
  "tags": ["authentication", "oauth2", "security", "backend"],
  "filename": "2025-08-29-143000-oauth2-implementation.json",
  "path": "gs://coditect-conversations/123e4567/2025/08/29/550e8400.json",
  "status": "Active",
  "created_at": "2025-08-29T14:30:00Z",
  "updated_at": "2025-08-29T16:45:00Z",
  "message_count": 47,
  "token_count": 125000
}

Architecture Discussion

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "567e8901-e89b-12d3-a456-426614174000",
  "session_id": "session-2025-08-28-09-00-00",
  "ai_provider": "claude",
  "title": "Microservices vs Monolith Architecture Decision",
  "description": "Evaluated architecture options for scaling, decided on modular monolith",
  "tags": ["architecture", "system-design", "scaling", "decision"],
  "filename": "2025-08-28-090000-architecture-decision.json",
  "path": "gs://coditect-conversations/123e4567/2025/08/28/660e8400.json",
  "status": "Active",
  "created_at": "2025-08-28T09:00:00Z",
  "updated_at": "2025-08-28T11:30:00Z",
  "message_count": 32,
  "token_count": 87500
}

Bug Investigation

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "678e9012-e89b-12d3-a456-426614174000",
  "session_id": "session-2025-08-27-23-45-00",
  "ai_provider": "gemini",
  "title": "Debug Memory Leak in WebSocket Handler",
  "description": "Found and fixed memory leak caused by unclosed connections",
  "tags": ["debugging", "memory-leak", "websocket", "production-issue"],
  "filename": "2025-08-27-234500-memory-leak-debug.json",
  "path": "gs://coditect-conversations/123e4567/2025/08/27/770e8400.json",
  "status": "Active",
  "created_at": "2025-08-27T23:45:00Z",
  "updated_at": "2025-08-28T02:15:00Z",
  "message_count": 89,
  "token_count": 156000
}

Conversation Content Structure (External File)

While not part of the model, conversation files typically contain:

{
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {
    "exported_at": "2025-08-29T16:45:00Z",
    "export_version": "1.0",
    "platform": "coditect"
  },
  "messages": [
    {
      "id": "msg-001",
      "role": "user",
      "content": "I need to implement OAuth2 authentication...",
      "timestamp": "2025-08-29T14:30:00Z",
      "attachments": []
    },
    {
      "id": "msg-002",
      "role": "assistant",
      "content": "I'll help you implement OAuth2 authentication...",
      "timestamp": "2025-08-29T14:30:15Z",
      "model": "claude-3-opus",
      "tokens": {
        "prompt": 150,
        "completion": 500
      }
    }
  ],
  "artifacts": {
    "code_files": [
      {
        "filename": "oauth2_handler.rs",
        "language": "rust",
        "content": "..."
      }
    ],
    "diagrams": [],
    "decisions": []
  }
}

Database Schema

Primary Storage Pattern

Key: /{tenant_id}/conversations/{conversation_id}
Value: JSON serialized Conversation object

Secondary Indexes

# Conversations by user
/{tenant_id}/conversations_by_user/{user_id} -> [conversation_ids]

# Conversations by session
/{tenant_id}/conversations_by_session/{session_id} -> conversation_id

# Conversations by tag
/{tenant_id}/conversations_by_tag/{tag} -> [conversation_ids]

# Conversations by date
/{tenant_id}/conversations_by_date/{YYYY-MM-DD} -> [conversation_ids]

# Conversations by provider
/{tenant_id}/conversations_by_provider/{provider} -> [conversation_ids]

Search Patterns

Full-Text Search

struct ConversationSearch {
    query: String,
    tags: Option<Vec<String>>,
    user_id: Option<Uuid>,
    date_range: Option<(DateTime<Utc>, DateTime<Utc>)>,
    ai_provider: Option<String>,
    min_messages: Option<u32>,
    max_results: usize
}

Tag Taxonomy

Common tags for categorization:

• Topic: backend, frontend, database, infrastructure
• Type: development, debugging, architecture, review
• Language: rust, typescript, python, sql
• Priority: critical, high, medium, low
• Status: resolved, ongoing, blocked, planned

Related Code

Source Files

• Model: /src/models/conversation.rs
• Repository: /src/db/repositories/conversation_repository.rs
• Export Service: /src/services/conversation_export/mod.rs
• API Handler: /src/api/handlers/conversation.rs
• Search Service: /src/services/conversation_search.rs

Key Methods

impl Conversation {
    fn new(
        tenant_id: Uuid,
        user_id: Uuid,
        session_id: String,
        ai_provider: String,
        title: String
    ) -> Self
    
    fn add_tags(&mut self, tags: Vec<String>)
    fn update_counts(&mut self, messages: u32, tokens: u32)
    fn archive(&mut self)
    fn restore(&mut self)
}

impl ConversationRepository {
    async fn create(&self, conversation: &Conversation) -> Result<()>
    async fn get_by_id(&self, tenant_id: &Uuid, id: &Uuid) -> Result<Option<Conversation>>
    async fn list_by_user(&self, tenant_id: &Uuid, user_id: &Uuid) -> Result<Vec<Conversation>>
    async fn search(&self, criteria: ConversationSearch) -> Result<Vec<Conversation>>
    async fn get_by_tags(&self, tenant_id: &Uuid, tags: &[String]) -> Result<Vec<Conversation>>
}

API Endpoints

Conversation Management

• POST /api/conversations - Create conversation record
• GET /api/conversations - List conversations
• GET /api/conversations/{id} - Get conversation metadata
• PUT /api/conversations/{id} - Update metadata
• DELETE /api/conversations/{id} - Soft delete

Search and Discovery

• POST /api/conversations/search - Full-text search
• GET /api/conversations/tags - List all tags
• GET /api/conversations/by-tag/{tag} - Get by tag
• GET /api/conversations/recent - Recent conversations

Export and Import

• POST /api/conversations/{id}/export - Export conversation
• GET /api/conversations/{id}/content - Get full content
• POST /api/conversations/import - Import from file

Use Cases

Knowledge Management

// Find all conversations about a specific error
let error_conversations = conversation_service
    .search(ConversationSearch {
        query: "memory leak websocket",
        tags: Some(vec!["debugging".to_string()]),
        ..Default::default()
    })
    .await?;

// Learn from past solutions
for conv in error_conversations {
    let content = storage.get_conversation_content(&conv.path).await?;
    // Extract solutions and patterns
}

Team Learning

// Share architectural decisions
let architecture_convs = conversation_repo
    .get_by_tags(&tenant_id, &["architecture", "decision"])
    .await?;

// Create learning resources
for conv in architecture_convs {
    learning_service.create_article_from_conversation(conv).await?;
}

Compliance and Audit

// Export all conversations for a user (GDPR)
let user_conversations = conversation_repo
    .list_by_user(&tenant_id, &user_id)
    .await?;

for conv in user_conversations {
    exporter.add_conversation(&conv).await?;
}

Storage Strategy

Hot Storage (Active)

• Recent conversations (< 30 days)
• Frequently accessed
• Full-text indexed
• Quick retrieval

Warm Storage (Archived)

• Older conversations (30-90 days)
• Compressed format
• Metadata indexed
• On-demand retrieval

Cold Storage (Long-term)

• Historical (> 90 days)
• Highly compressed
• Compliance retention
• Batch retrieval only

Privacy and Security

Access Control

• Users see only their conversations
• Managers can view team conversations
• Admins have full access
• Sharing requires explicit permission

Data Protection

• Conversation content encrypted at rest
• PII detection and masking
• Secure deletion procedures
• Audit trail for access

Compliance

• GDPR export capability
• Retention policy enforcement
• Right to deletion
• Anonymization support

Performance Optimization

Indexing Strategy

• Primary key index on conversation_id
• Secondary indexes for common queries
• Full-text search on titles and tags
• Date-based partitioning

Caching

• Recent conversations in memory
• Tag cloud caching
• Search results caching
• User's conversation list

Batch Operations

// Batch tag update
conversation_service
    .batch_update_tags(conversation_ids, tags_to_add, tags_to_remove)
    .await?;

// Batch archive
conversation_service
    .batch_archive_older_than(Duration::days(90))
    .await?;

Analytics and Insights

Metrics

• Conversations per user/day
• Average message count
• Token usage trends
• Popular tags
• AI provider distribution

Insights Generation

struct ConversationInsights {
    most_discussed_topics: Vec<(String, usize)>,
    peak_usage_hours: Vec<u8>,
    average_conversation_length: Duration,
    common_patterns: Vec<Pattern>,
    knowledge_gaps: Vec<String>
}

Integration Points

With AI Agents

• Auto-export after session
• Title generation from content
• Tag suggestion from context
• Summary generation

With Project Management

• Link conversations to tasks
• Reference in documentation
• Include in project history
• Decision tracking

With Learning System

• Extract code examples
• Generate tutorials
• Create documentation
• Build knowledge base

Future Enhancements

Advanced Features

1. Conversation Threading: Link related conversations
2. Collaborative Sessions: Multi-user conversations
3. Version Control: Track conversation edits
4. Smart Summaries: AI-generated summaries

Search Improvements

1. Semantic Search: Understanding-based search
2. Code Search: Find code snippets in conversations
3. Similar Conversations: ML-based recommendations
4. Query Builder: Advanced search UI

Knowledge Management

1. Auto-categorization: ML-based tagging
2. Knowledge Graph: Relationship mapping
3. Insight Extraction: Automatic learning
4. Team Analytics: Usage patterns

Integration Features

1. IDE Plugin: Access from development environment
2. Slack Integration: Share conversations
3. Documentation Sync: Auto-update docs
4. API Access: Programmatic retrieval

---

Last Updated: 2025-08-29 Version: 1.0