Architecture
Lillo is built on a serverless-first architecture using Next.js 15 and Vercel, designed for scalable AI agent deployment and management.
System Architecture
Core Components
Lillo Framework
βββ Frontend (Next.js 15 App Router)
βββ API Layer (Vercel Edge Functions)
βββ Service Layer
β βββ LLM Factory
β βββ Agent Configuration
β βββ Model Preferences
βββ Storage Layer
β βββ Vercel Postgres
β βββ Redis KV Store
βββ Integration Layer
βββ Telegram Bot API
βββ OpenAI API
βββ External Services
Component Architecture
1. Frontend Layer
src/app/ # Next.js 15 App Router
βββ api/ # API Routes
β βββ webhook/ # Webhook handlers
β βββ telegram/ # Telegram endpoints
β βββ openai/ # AI endpoints
β βββ market/ # Market data
β βββ dalle/ # Image generation
β βββ weather/ # Weather data
β βββ token/ # Token management
β βββ session/ # Session handling
β βββ rpc/ # RPC endpoints
β βββ redis/ # KV store access
βββ hooks/ # React hooks
βββ layout.tsx # Root layout
2. Service Layer
src/lib/services/ # Core Services
βββ LLMFactory.ts # Multi-model LLM integration
β βββ OpenAI
β βββ DeepSeek
β βββ Gemini
β βββ Function Calling
βββ AgentConfigService.ts # Agent management
β βββ Configuration
β βββ State Management
β βββ Secure Storage
βββ ModelPreferences.ts # Model settings
src/utils/ # Utility Services
βββ prompts.ts # Prompt management
βββ telegram.ts # Telegram integration
βββ nlp.ts # Natural language processing
βββ market.ts # Market data processing
βββ kv.ts # Key-value storage
βββ encryption.ts # Security utilities
βββ adminCheck.ts # Permission system
βββ image.ts # Image generation
3. Database Layer
src/lib/db/ # Database Layer
βββ schema.ts # Table definitions
βββ data.ts # Data operations
βββ metrics.ts # Analytics
βββ migrations/ # Schema updates
Data Flow Architecture
1. Message Processing
graph LR
A[Telegram Message] --> B[Webhook Handler]
B --> C[Message Processor]
C --> D[LLM Factory]
D --> E[Function Calling]
E --> F[Response Handler]
2. State Management
graph TD
A[Agent State] --> B[Redis KV Store]
B --> C[PostgreSQL]
C --> D[Cache Layer]
3. Function Calling
const tools = [{
type: "function",
function: {
name: "generate_image",
description: "Generate an image based on the user's request",
parameters: {
type: "object",
properties: {
prompt: {
type: "string",
description: "The description of the image to generate"
}
},
required: ["prompt"]
}
}
},
{
type: "function",
function: {
name: "get_weather",
description: "Get current weather data",
parameters: {
type: "object",
properties: {
location: {
type: "object",
description: "Location details",
properties: {
name: { type: "string" },
country: { type: "string" },
coordinates: {
type: "object",
properties: {
lat: { type: "number" },
lon: { type: "number" }
}
}
}
}
}
}
}
}]
Security Architecture
1. Authentication
// Multi-layer auth system
βββ API Authentication
β βββ Vercel Edge Config
β βββ Environment Variables
βββ User Authentication
β βββ Telegram Verification
β βββ Admin Role System
βββ Agent Authentication
βββ Encrypted Configs
βββ Secure Storage
2. Permission System
export enum AdminRole {
USER = 'user', // Regular user
MODERATOR = 'moderator', // Can delete messages
ADMIN = 'admin', // Can manage users
OWNER = 'owner' // Can change group info
}
Performance Architecture
1. Caching Strategy
Redis KV Store
Agent configurations
Command metrics
Rate limiting
Session data
2. Database Optimization
Indexed queries
Connection pooling
Prepared statements
Type safety
3. Edge Functions
Webhook handling
API routes
Static generation
Response streaming
Development Architecture
1. Project Structure
src/
βββ app/ # Next.js application
βββ lib/ # Core libraries
βββ utils/ # Utilities
βββ types/ # TypeScript types
βββ data/ # Static data
βββ telegram/ # Bot implementation
2. Type Safety
// Strict type checking
{
"compilerOptions": {
"strict": true,
"target": "ES2022",
"lib": ["dom", "dom.iterable", "esnext"],
"module": "esnext",
"moduleResolution": "bundler",
"jsx": "preserve",
"noEmit": true
}
}
Best Practices
1. Code Organization
Feature-based structure
Clear separation of concerns
Dependency injection
Type safety
2. Error Handling
Global error boundary
Service-level recovery
Logging and monitoring
User feedback
3. Performance
Edge function optimization
Response streaming
Cache management
Query optimization
Related Documentation
Last updated