AI Knowledge Graph Builder

A full-stack TypeScript application that uses AI to extract entities and relationships from text, building cumulative knowledge graphs with interactive visualization and persistent storage.

Overview

This application analyzes text using OpenAI's GPT-4o-mini model to extract entities (people, organizations, locations, concepts, events) and their relationships, building an interactive knowledge graph that persists across multiple analyses within a session.

Architecture

Frontend (React + Vite + TypeScript)

• Framework: React 18 with TypeScript and Vite for fast development
• UI Components: Radix UI primitives with Tailwind CSS for styling
• Graph Visualization: ReactFlow for interactive node-link diagrams
• State Management: React hooks with session-based persistence
• Type Safety: Shared TypeScript schemas with runtime Zod validation

Backend (Express + TypeScript)

• Server: Express.js with TypeScript in ESM module format
• AI Integration: OpenAI GPT-4o-mini for entity/relationship extraction
• Database: PostgreSQL with Drizzle ORM for type-safe operations
• Session Management: Express sessions with PostgreSQL storage
• API Design: RESTful endpoints with centralized error handling

System Flow

1. Text Analysis Pipeline

User Input (Text) 
    ↓
[TextInputPanel] - User enters text for analysis
    ↓
POST /api/analyze - Frontend sends text to backend
    ↓
[KnowledgeGraphService] - AI processes text using OpenAI
    ↓
Structured JSON Response - Entities and relationships extracted
    ↓
[GraphMerger] - Merges new graph with existing session graph
    ↓
[Storage] - Saves individual analysis to PostgreSQL
    ↓
Updated Knowledge Graph returned to frontend

2. Graph Building & Merging

The system implements cumulative graph building across multiple text analyses:

• Entity Merging: Entities are merged by ID to prevent duplicates
• Relationship Merging: Relationships use composite keys (source-target-type) with deterministic hashed IDs
• Session Persistence: Graphs accumulate in Express sessions until explicitly cleared
• Individual Storage: Each analysis is also stored separately in the database

3. Data Storage Architecture

Session Storage (Temporary)

req.session.graph = {
  entities: Entity[],
  relationships: Relationship[]
}

Database Storage (Persistent)

analysis_messages (
  id: serial primary key,
  text: text,
  entities: jsonb,
  relationships: jsonb,
  created_at: timestamp
)

4. Frontend Visualization

• EntityList: Displays all extracted entities with type badges
• RelationshipList: Shows connections between entities
• GraphVisualization: Interactive ReactFlow diagram with node highlighting
• Export Functionality: Download complete graphs as JSON files

Key Components

Backend Services

KnowledgeGraphService

• Interfaces with OpenAI API using GPT-4o-mini model
• Enforces structured JSON responses for consistent data extraction
• Uses low temperature (0.3) for deterministic outputs
• Extracts entities with types: person, organization, location, concept, event, other

GraphMerger

• Merges new analysis results with existing session graphs
• Prevents duplicate entities and relationships
• Generates deterministic IDs using SHA-256 hashing
• Maintains referential integrity across merged graphs

Storage

• PostgreSQL integration using Neon serverless infrastructure
• Drizzle ORM for type-safe database operations
• Stores individual analyses with full entity/relationship data
• WebSocket-based connection pooling for optimal performance

Frontend Components

Home - Main Application Container

• Manages application state (graph, analysis status, UI interactions)
• Orchestrates communication between all child components
• Handles API calls for analysis, clearing, and error management

ExportDialog

• Provides JSON export functionality for knowledge graphs
• Generates timestamped filenames for downloaded files
• Handles export errors gracefully with user feedback

GraphVisualization

• ReactFlow-based interactive graph display
• Node highlighting for entity focus
• Responsive layout with zoom and pan capabilities

API Endpoints

POST /api/analyze

Purpose: Analyze text and extract knowledge graph

Request: { text: string }
Response: KnowledgeGraph { entities: Entity[], relationships: Relationship[] }

Flow:

1. Validates input with Zod schema
2. Calls AI service for entity/relationship extraction
3. Merges results with existing session graph
4. Saves individual analysis to database
5. Returns merged graph to frontend

POST /api/clear

Purpose: Reset session graph to start fresh analysis

Request: {}
Response: { success: boolean, message: string }

Environment Setup

Required Environment Variables

OPENAI_API_KEY=your_openai_api_key
DATABASE_URL=postgresql://connection_string

Development Commands

npm install          # Install dependencies
npm run dev          # Start development server
npm run build        # Build for production
npm run db:push      # Push database schema changes

Data Models

Entity Structure

interface Entity {
  id: string;
  name: string;
  type: 'person' | 'organization' | 'location' | 'concept' | 'event' | 'other';
  description?: string;
}

Relationship Structure

interface Relationship {
  id: string;
  source: string;  // Entity ID
  target: string;  // Entity ID
  type: string;    // Descriptive relationship type
}

Knowledge Graph Structure

interface KnowledgeGraph {
  entities: Entity[];
  relationships: Relationship[];
}

Features

Core Functionality

• ✅ AI-powered entity and relationship extraction
• ✅ Cumulative graph building across multiple analyses
• ✅ Interactive graph visualization with ReactFlow
• ✅ Session-based graph persistence
• ✅ Individual analysis storage in PostgreSQL
• ✅ JSON export functionality
• ✅ Graph clearing and reset capabilities

Technical Features

• ✅ Full TypeScript type safety across frontend and backend
• ✅ Shared schema validation with Zod
• ✅ Responsive UI with Tailwind CSS
• ✅ Error handling and user feedback with toast notifications
• ✅ Deterministic ID generation for consistent data merging
• ✅ WebSocket-optimized database connections

Development Environment

This project runs in a dev container on Ubuntu 24.04.2 LTS with access to standard development tools including Docker, Git, and various CLI utilities. The application is designed for deployment on Replit with their Neon PostgreSQL infrastructure.

File Structure

├── client/                 # React frontend application
│   ├── src/
│   │   ├── components/    # Reusable UI components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── pages/         # Application pages
│   │   └── lib/           # Utility libraries
├── server/                # Express backend application
│   ├── services/          # Business logic services
│   ├── routes.ts          # API route definitions
│   ├── storage.ts         # Database interface
│   └── index.ts           # Server entry point
├── shared/                # Shared TypeScript schemas
│   └── schema.ts          # Zod validation schemas
└── Configuration files for Vite, TypeScript, Tailwind, etc.

This architecture provides a robust, type-safe, and scalable foundation for building and visualizing AI-extracted knowledge graphs with persistent storage and session management.