# Architecture

## 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

```typescript
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

```typescript
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

```typescript
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

```mermaid
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

```mermaid
graph TD
    A[Agent State] --> B[Redis KV Store]
    B --> C[PostgreSQL]
    C --> D[Cache Layer]
```

### 3. Function Calling

```typescript
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

```typescript
// 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

```typescript
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

```typescript
src/
├── app/              # Next.js application
├── lib/             # Core libraries
├── utils/           # Utilities
├── types/           # TypeScript types
├── data/           # Static data
└── telegram/       # Bot implementation
```

### 2. Type Safety

```typescript
// 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](https://docs.lillo.ai/core-concepts/database)
* [Agent System](https://docs.lillo.ai/ai-agent-framework/overview)
* [API Reference](https://github.com/lillo-ai/website/blob/master/docs/reference/api.md)