Nexus/MCP-ARCHITECTURE.md

# 🎨 Arquitectura MCP - Nexus AI

## Basado en ChatGPT UI Kit (Figma) + Lobe UI

**Referencia Figma**: https://www.figma.com/design/e0F6ZXsMuseZpKbc6IU3jR/ChatGPT-UI-Kit--AI-Chat--Community-?node-id=676-342

---

## 📐 Estructura MCP (Model-Context-Pattern)

### Model (Datos y Lógica)
- **`useChat.ts`** - Hook principal con lógica de negocio
  - Gestión de mensajes
  - Estado de conversaciones
  - Socket.IO communication
  - State management

### Context (Tema y Configuración)
- **`theme.ts`** - Tokens de diseño basados en Figma
  - Colores ChatGPT UI Kit
  - Gradientes Lobe UI
  - Espaciado sistema
  - Z-index layers

### Pattern (Componentes y Estilos)
- **Layout Components** - Estructura visual
- **UI Components** - Elementos interactivos
- **Style Components** - CSS-in-JS con antd-style

---

## 🏗️ Arquitectura de Componentes

```
App (ThemeProvider)
├── Layout
│   ├── Sidebar
│   │   ├── Header
│   │   │   ├── CloseButton (mobile)
│   │   │   └── NewChatButton
│   │   ├── Conversations
│   │   │   ├── SectionTitle
│   │   │   └── ConversationItem[]
│   │   └── Footer
│   │       └── UserProfile
│   │
│   └── MainContent
│       ├── ChatHeader (mobile)
│       │   ├── MenuButton
│       │   ├── Title
│       │   └── Actions
│       │
│       └── ChatArea
│           ├── MessagesContainer
│           │   ├── WelcomeScreen
│           │   └── ChatMessage[]
│           │       ├── Avatar
│           │       └── Content
│           │
│           └── InputArea
│               └── ChatInput
│                   ├── AttachButton
│                   ├── Textarea
│                   └── SendButton
│
└── Overlay (mobile)
```

---

## 🎨 Sistema de Diseño

### Colores Base (Figma ChatGPT UI Kit)

```typescript
// Backgrounds
colorBgBase: '#0a0a0a'        // Dark base
colorBgContainer: '#171717'   // Container
colorBgElevated: '#202020'    // Elevated

// Text
colorTextBase: '#ececf1'      // Primary text
colorTextSecondary: '#c5c5d2' // Secondary
colorTextTertiary: '#8e8ea0'  // Tertiary

// Borders
colorBorder: 'rgba(255, 255, 255, 0.06)'
```

### Gradientes (Lobe UI Style)

```typescript
// Primary - Purple
linear-gradient(135deg, #667eea 0%, #764ba2 100%)

// Accent - Cyan
linear-gradient(135deg, #4facfe 0%, #00f2fe 100%)

// Success - Green
linear-gradient(135deg, #43e97b 0%, #38f9d7 100%)
```

### Glassmorphism

```css
background: rgba(17, 17, 17, 0.7);
backdrop-filter: blur(20px);
border: 1px solid rgba(255, 255, 255, 0.08);
```

---

## 📁 Estructura de Archivos

```
client/src/
├── App.tsx                    # App principal con layout MCP
├── App.css                    # Estilos globales mínimos
│
├── components/                # Componentes UI
│   ├── SidebarNew.tsx        # ✨ Sidebar rediseñado
│   ├── ChatHeader.tsx        # ✨ Header mobile
│   ├── ChatContainer.tsx     # Container de chat
│   ├── ChatMessage.tsx       # Mensaje individual
│   ├── ChatInput.tsx         # Input personalizado
│   └── WelcomeScreen.tsx     # Pantalla bienvenida
│
├── hooks/                     # Custom hooks
│   └── useChat.ts            # Hook principal de chat
│
├── styles/                    # ✨ Sistema de estilos
│   ├── theme.ts              # Tema ChatGPT + Lobe UI
│   └── appLayout.styles.ts   # Estilos de layout
│
└── types/                     # TypeScript types
    └── index.ts              # Tipos globales
```

---

## 🎯 Características Implementadas

### Layout Principal
- ✅ **Sidebar glassmorphism** - Blur 20px + transparencia
- ✅ **Layout responsive** - Desktop + Mobile
- ✅ **Overlay mobile** - Backdrop blur al abrir sidebar
- ✅ **Smooth transitions** - 0.3s ease

### Sidebar (Basado en Figma)
- ✅ **Header con botón nuevo chat** - Gradiente purple
- ✅ **Lista de conversaciones** - Con sección "Recientes"
- ✅ **User profile** - Avatar + info
- ✅ **Scroll personalizado** - 4px thin purple
- ✅ **Hover effects** - Transform translateX(4px)
- ✅ **Active state** - Purple tint + border

### Chat Header (Mobile)
- ✅ **Menu toggle** - Abre/cierra sidebar
- ✅ **Title** - Nombre de la app
- ✅ **Actions** - Settings + Profile
- ✅ **Glassmorphism** - Blur 12px

### Chat Container
- ✅ **Messages area** - Scroll infinito
- ✅ **Welcome screen** - Logo + sugerencias
- ✅ **Typing indicator** - 3 dots animados
- ✅ **Custom input** - Auto-resize + Enter send

---

## 🔧 Configuración del Tema

### ThemeProvider Setup

```tsx
import { ThemeProvider } from 'antd-style';
import { chatGPTTheme } from './styles/theme';

<ThemeProvider theme={chatGPTTheme}>
  <App />
</ThemeProvider>
```

### Usando Tokens en Componentes

```tsx
import { createStyles } from 'antd-style';

const useStyles = createStyles(({ css, token }) => ({
  container: css`
    background: ${token.colorBgContainer};
    color: ${token.colorTextBase};
    border-radius: ${token.borderRadius}px;
  `,
}));
```

### Usando Colores Custom (Lobe UI)

```tsx
import { lobeUIColors } from '../styles/theme';

const useStyles = createStyles(({ css }) => ({
  button: css`
    background: ${lobeUIColors.gradient.primary};
  `,
}));
```

---

## 📱 Responsive Design

### Breakpoints

```css
/* Desktop First */
@media (max-width: 768px) {
  /* Mobile styles */
}
```

### Mobile Behavior

#### Sidebar
```css
/* Desktop */
width: 260px;
position: relative;

/* Mobile */
position: fixed;
left: -260px;  /* Hidden by default */
z-index: 1000;

&.open {
  left: 0;  /* Slide in */
}
```

#### Header
```css
/* Desktop */
display: none;

/* Mobile */
display: flex;
height: 48px;
```

---

## 🎨 Componentes Clave

### 1. Sidebar

**Props**:
```typescript
interface SidebarProps {
  conversations: Conversation[];
  activeConversationId: string;
  onNewChat: () => void;
  onSelectConversation: (id: string) => void;
  onClose?: () => void;  // Para mobile
}
```

**Características**:
- Header con botón gradiente
- Lista scrollable con sección titles
- User profile en footer
- Close button para mobile

### 2. ChatHeader

**Props**:
```typescript
interface ChatHeaderProps {
  onMenuClick?: () => void;
  onSettingsClick?: () => void;
  onProfileClick?: () => void;
  title?: string;
}
```

**Características**:
- Solo visible en mobile
- Menu toggle para sidebar
- Actions buttons (settings, profile)
- Glassmorphism style

### 3. ChatContainer

**Props**:
```typescript
interface ChatContainerProps {
  messages: Message[];
  isTyping: boolean;
  onSendMessage: (content: string) => void;
}
```

**Características**:
- Messages scrollable area
- Welcome screen cuando vacío
- Typing indicator
- Custom input area

---

## 🎯 Patrón de Estado

### useChat Hook (Model)

```typescript
const {
  messages,              // Message[]
  conversations,         // Conversation[]
  activeConversationId,  // string
  isTyping,             // boolean
  sendMessage,          // (content: string) => void
  createNewConversation, // () => void
  selectConversation,   // (id: string) => void
} = useChat();
```

### Flujo de Datos

```
Usuario → Acción
  ↓
useChat Hook
  ↓
Socket.IO → Backend
  ↓
Backend responde
  ↓
useChat actualiza estado
  ↓
Componentes re-renderizan
```

---

## 🚀 Cómo Usar

### 1. Iniciar Aplicación
```bash
npm run dev:all
```

### 2. Abrir en Navegador
```
http://localhost:3001
```

### 3. Probar Features
- ✅ Click "Nuevo chat" → Crea conversación
- ✅ Escribir mensaje → Enter envía
- ✅ Ver respuesta AI → Con typing indicator
- ✅ Mobile: Menu button → Abre sidebar
- ✅ Mobile: Overlay → Cierra sidebar

---

## 🎨 Estilos Destacados

### Sidebar Container
```css
background: rgba(13, 13, 13, 0.8);
backdrop-filter: blur(20px);
border-right: 1px solid rgba(255, 255, 255, 0.06);
```

### Nuevo Chat Button
```css
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
box-shadow: 
  0 4px 16px rgba(0, 0, 0, 0.4),
  0 0 20px rgba(102, 126, 234, 0.3);

&:hover {
  transform: translateY(-2px);
  box-shadow: 
    0 8px 32px rgba(0, 0, 0, 0.5),
    0 0 30px rgba(102, 126, 234, 0.5);
}
```

### Conversation Item (Active)
```css
background: rgba(102, 126, 234, 0.1);
border-color: #667eea;
color: white;

svg {
  opacity: 1;
}
```

### User Profile
```css
border: 1px solid rgba(255, 255, 255, 0.08);
background: transparent;

&:hover {
  background: rgba(255, 255, 255, 0.05);
  border-color: rgba(102, 126, 234, 0.4);
  transform: translateY(-2px);
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.4);
}
```

---

## 📊 Comparación

### Antes
```
App
└── Container
    ├── Sidebar (fijo)
    └── Chat
```

### Ahora (MCP)
```
App (ThemeProvider)
├── Theme Config (chatGPTTheme)
├── Layout (appLayout.styles)
│   ├── Sidebar (glassmorphism)
│   ├── MainContent
│   │   ├── Header (mobile)
│   │   └── ChatArea
│   └── Overlay (mobile)
└── State (useChat hook)
```

**Ventajas**:
- ✅ Separación clara de responsabilidades
- ✅ Tema centralizado y reutilizable
- ✅ Estilos organizados por contexto
- ✅ Mobile-first responsive
- ✅ Más escalable y mantenible

---

## 🔮 Extensiones Futuras

### Fácil de Agregar

#### 1. Settings Panel
```tsx
<SettingsPanel
  theme={theme}
  onThemeChange={setTheme}
/>
```

#### 2. Search Conversations
```tsx
<SearchBar
  onSearch={filterConversations}
/>
```

#### 3. Conversation Actions
```tsx
<ConversationActions
  onRename={handleRename}
  onDelete={handleDelete}
  onArchive={handleArchive}
/>
```

#### 4. Themes Switcher
```tsx
const themes = ['dark', 'light', 'auto'];

<ThemeProvider theme={themes[selected]}>
  <App />
</ThemeProvider>
```

---

## ✅ Checklist de Implementación

### Estructura
- [x] Crear `styles/theme.ts`
- [x] Crear `styles/appLayout.styles.ts`
- [x] Crear `components/SidebarNew.tsx`
- [x] Crear `components/ChatHeader.tsx`
- [x] Actualizar `App.tsx` con layout MCP

### Estilos
- [x] Colores Figma ChatGPT UI Kit
- [x] Gradientes Lobe UI
- [x] Glassmorphism effects
- [x] Responsive mobile
- [x] Animations y transitions

### Funcionalidad
- [x] Sidebar toggle mobile
- [x] Overlay con backdrop blur
- [x] Scroll personalizado
- [x] Active states
- [x] Hover effects

---

## 📚 Referencias

- **Figma Design**: ChatGPT UI Kit (node-id=676-342)
- **Lobe UI**: https://ui.lobehub.com
- **antd-style**: https://ant-design.github.io/antd-style
- **Pattern**: MCP (Model-Context-Pattern)

---

**Fecha de implementación**: 14 de Febrero, 2026  
**Arquitectura**: MCP (Model-Context-Pattern)  
**Design System**: ChatGPT UI Kit + Lobe UI  
**Estado**: ✅ Implementado y Funcional  
**Responsive**: ✅ Desktop + Mobile