convez.ai
MCP ServerDesenvolvimento WebAvançado
ellttdave

Plataforma de Análise de Performance de Atletas

ellttdave/athlete-performance-platform-showcase

Showcase de arquitetura LLM + RAG + MCP em TypeScript

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server TypeScript que demonstra integração avançada de LLM com Claude, sistema RAG com embeddings vetoriais e arquitetura full-stack moderna. Implementa padrões de produção para chamadas estruturadas a ferramentas, processamento de documentos com Google Document AI e busca semântica em PostgreSQL com pgvector.

Instalação

$npx convez-ai ellttdave/athlete-performance-platform-showcase

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 ano
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Arquitetura de referência para integração LLM em produção
  • Implementação de padrão RAG com vector search e PostgreSQL
  • Processamento de documentos PDF com extração inteligente
  • Padrão MCP customizado para separação de concerns

Veredito

Projeto técnico sólido que serve como blueprint para aplicações LLM em produção, com implementação genuína de RAG, processamento de documentos e padrão MCP. Recomendado para quem busca referência de arquitetura escalável, não para uso direto em produção sem customização.

README

A tradução para o português deste README ainda está na fila.

Release License Last commit Stars

Top language Repo size

Athlete Performance Analytics Platform - Technical Showcase

A production application demonstrating advanced LLM integration, RAG systems, and modern full-stack architecture patterns.

🎯 Project Overview

This repository showcases the technical architecture and implementation patterns from a production application that integrates:

  • LLM Integration (Anthropic Claude) with structured tool calling
  • RAG System (Retrieval-Augmented Generation) with vector embeddings
  • MCP-like Architecture for clean separation of concerns
  • Modern Full-Stack development with Next.js, TypeScript, and PostgreSQL

Note: This repository contains sanitized code examples and architecture documentation for showcaase purposes. The full production application remains private to protect intellectual property.

🏗️ Architecture Highlights

MCP-Like Tool Integration Pattern

A custom architecture pattern that mimics Model Context Protocol (MCP) to provide clean separation between LLM communication logic and data functions.

Key Benefits:

  • Single gateway for all LLM tool calls
  • Easy migration path to real MCP server
  • Extensible tool registry pattern
  • Comprehensive error handling

View Architecture Details →

RAG Implementation

A production-ready RAG system using vector embeddings and semantic search.

Key Features:

  • Google Document AI for advanced text extraction (Form Parser, Layout Parser)
  • Automatic PDF splitting for large files (>15 pages or >4MB)
  • OpenAI embeddings (text-embedding-3-small)
  • pgvector for PostgreSQL vector similarity search
  • Vercel Blob Storage for document persistence
  • Individual document re-processing to avoid timeout issues
  • Fallback mechanisms (unpdf) for reliability
  • Automatic knowledge base integration
  • Top-K retrieval with similarity scoring

Architecture Note:

  • RAG is used for general knowledge, research articles, and contextual explanations
  • Precise numeric/reference data is stored in PostgreSQL (not RAG) for deterministic queries

View RAG Implementation →

Full-Stack Design

Modern web application architecture with:

  • Frontend: Next.js 14, React 18, TypeScript, Tailwind CSS
  • Backend: Next.js API Routes, Server Actions
  • Database: PostgreSQL (Neon) with Prisma ORM, pgvector extension
  • AI/ML: Anthropic Claude API, OpenAI Embeddings
  • Document Processing: Google Document AI, pdf-lib for PDF splitting
  • Storage: Vercel Blob Storage for document persistence
  • Deployment: Vercel

View Tech Stack Details →

📚 Documentation

💻 Code Examples

Sanitized code examples demonstrating key patterns:

🛠️ Key Technical Features

1. Custom Tool Registry Pattern

Clean separation between LLM communication and data functions:

// Extensible tool registry
const TOOL_REGISTRY = {
  'analyze_data': {
    description: 'Comprehensive data analysis tool',
    handler: async (params) => { /* ... */ }
  }
}

2. RAG System with Vector Search

Production-ready retrieval-augmented generation:

  • Vector embedding generation
  • Semantic similarity search
  • Knowledge base integration
  • Context retrieval for LLM

3. Structured LLM Outputs

Type-safe JSON generation with validation:

  • Schema validation
  • Error handling
  • Data integrity measures
  • Reliable structured outputs

4. Production-Ready Patterns

  • Comprehensive error handling
  • Logging and monitoring
  • Type safety with TypeScript
  • Scalable architecture

💡 Technical Insights

Why MCP-Like Architecture?

  • Provides clean separation of concerns
  • Makes LLM integration maintainable
  • Allows easy addition of new tools
  • Facilitates migration to real MCP server

RAG Implementation Decisions

  • Chose pgvector over external vector DB for simplicity
  • OpenAI embeddings for reliability
  • Top-K retrieval for performance
  • Integration with existing PostgreSQL infrastructure

LLM Integration Challenges

  • Structured output reliability
  • Data integrity enforcement
  • Error handling and fallbacks
  • Token optimization

🚀 Key Achievements

  • ✅ Implemented custom MCP-like architecture for LLM tool integration
  • ✅ Built production RAG system with vector embeddings
  • ✅ Designed scalable data models for multi-modal analytics
  • ✅ Created evidence-based analysis engine with citation requirements
  • ✅ Deployed production application with optimized performance

📄 License

Technical showcase - Code examples are for demonstration and educational purposes.

Note: This repository contains sanitized code examples and architecture documentation. The full production application remains private to protect intellectual property.


Connect

Ver o original no GitHub

Bom para

Relacionados