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

• Database Schema
• Agent System
• API Reference