Architecture Overview

​

System Architecture

​

Core Technologies

​

Architecture Diagram

​

Key Design Principles

​

1. Server-First Architecture

• Keep API keys secure on the server
• Reduce client bundle size
• Enable streaming AI responses
• Handle sensitive operations server-side

​

2. Type Safety

• Compile-time type checking
• Runtime data validation
• Automatic type inference
• Safe API contracts

​

3. Modular Component Design

• UI Components: Reusable design system primitives
• AI Elements: Specialized AI interaction components
• Features: Domain-specific feature modules
• Shared: Cross-cutting concerns

​

4. Progressive Enhancement

• Server-side rendering for initial load
• Client-side hydration for interactivity
• Optimistic UI updates
• Graceful fallbacks

​

Data Flow

​

Chat Message Flow

​

Tool Execution Flow

1. User Input: User asks a question requiring backend data
2. AI Decision: LLM decides to use a tool (e.g., consultar_activos)
3. Tool Execution: Server executes tool with authenticated API call
4. Result Processing: Tool result is validated and normalized
5. AI Response: LLM uses tool result to formulate response
6. UI Rendering: Client renders result in interactive table

​

Security Model

​

Authentication

• Laravel Sanctum bearer token authentication
• Token stored in HTTP-only cookies (future enhancement)
• Silent login for session recovery
• Token injection per-request

​

API Security

• Rate limiting per IP address
• Input validation with Zod schemas
• Server-side API key management
• CORS configuration for production

​

Data Protection

• No sensitive data in client state
• Encrypted transport (HTTPS)
• Sanitized error messages
• Audit logging for tool calls

​

Performance Optimizations

​

Client-Side

• Dynamic Imports: Code splitting for heavy components
• React Suspense: Progressive loading of UI
• localStorage Caching: Persistent chat history
• Debounced Inputs: Optimized user input handling

​

Server-Side

• Streaming Responses: Real-time AI output
• Connection Pooling: Efficient backend API calls
• Response Caching: Cached AI tool results
• Edge Runtime: Fast cold starts on Vercel

​

AI Optimizations

• Token Limiting: Max 15 items per tool response
• Description Truncation: Reduce context size
• Step Limiting: Max 4 tool call steps
• Schema Optimization: Minimal JSON schemas

​

Deployment Architecture

┌─────────────────┐
│   Vercel Edge   │
│   (Frontend)    │
└────────┬────────┘
         │
         ├──► GROQ API (Chat)
         ├──► Gemini API (Vision/Voice)
         │
         └──► ┌─────────────────┐
              │ Laravel Backend │
              │   (GIMA API)    │
              └────────┬────────┘
                       │
                       └──► MySQL Database

┌─────────────────┐
│  localhost:3000 │
│  (Next.js Dev)  │
└────────┬────────┘
         │
         ├──► GROQ API (Chat)
         ├──► Gemini API (Vision/Voice)
         │
         └──► ┌─────────────────┐
              │ Laravel Herd    │
              │ localhost:8000  │
              └────────┬────────┘
                       │
                       └──► SQLite/MySQL

​

Scalability Considerations

​

Horizontal Scaling

• Stateless Next.js instances
• Shared session storage (future)
• Load-balanced backend API
• CDN for static assets

​

Vertical Scaling

• Efficient memory usage
• Optimized bundle size
• Lazy loading strategies
• Minimal re-renders

​

Monitoring & Observability

​

Logging

• Structured logging with custom logger
• Component-level log context
• Error tracking with stack traces
• Performance metrics

​

Error Handling

• Global error boundaries
• Graceful degradation
• User-friendly error messages
• Automatic retry logic

​

Next Steps