> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mypraxos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Understanding Praxos's system architecture and design

## System Overview

Praxos is built as a modular, event-driven AI assistant platform that integrates with multiple communication channels and external services.

```mermaid theme={null}
graph TB
    A[User] -->|Messages| B[Ingress Layer]
    B -->|Telegram| C[Message Queue]
    B -->|Discord| C
    B -->|Slack| C
    B -->|WhatsApp| C
    C -->|Tasks| D[Worker Pool]
    D -->|Process| E[LangGraph Agent]
    E -->|Uses| F[Tool Factory]
    F -->|Creates| G[Integration Tools]
    F -->|Creates| H[Communication Tools]
    F -->|Creates| I[Database Tools]
    E -->|Responses| J[Egress Layer]
    J -->|Sends| A
```

## Core Components

### Ingress Layer

The ingress layer handles incoming messages from various platforms:

* **FastAPI Server** (`src/ingress/api.py`) - Main HTTP/WebSocket server
* **Platform Adapters** - Telegram, Discord, Slack, WhatsApp adapters
* **Message Validation** - Input sanitization and validation
* **Queue Publishing** - Pushes messages to processing queue

### Message Queue

Uses Azure Service Bus (or Redis in local mode) for:

* Asynchronous message processing
* Load balancing across workers
* Retry mechanisms for failed tasks
* Priority-based task scheduling

### Worker Pool

Background workers (`src/workers/`) process tasks:

* **Agent Workers** - Run LangGraph agent loops
* **Scheduled Task Workers** - Execute recurring tasks
* **Ingestion Workers** - Process files and documents
* Auto-scaling based on queue depth

### LangGraph Agent

The core AI orchestration engine:

```python theme={null}
# Simplified agent flow
State -> Tool Selection -> Tool Execution -> State Update -> Response
```

Key features:

* Multi-step reasoning with LangGraph
* Conversational memory and context
* Dynamic tool selection
* Interrupt handling for long operations

### Tool Factory

Dynamically creates tools based on user context:

* **Integration Tools** - Google, Microsoft, Notion, etc.
* **Communication Tools** - Send messages, intermediate updates
* **Database Tools** - User preferences, context storage
* **Web Tools** - Browsing, search, content extraction
* **Utility Tools** - File processing, scheduling

## Data Flow

### Message Processing Flow

1. **Receive Message**
   * User sends message via platform (Telegram, Discord, etc.)
   * Platform webhook hits ingress endpoint
   * Message validated and normalized

2. **Queue & Route**
   * Message published to Azure Service Bus
   * Worker picks up message from queue
   * Worker loads user context from database

3. **Agent Processing**
   * LangGraph agent initialized with tools
   * Agent reasons about task
   * Agent executes tools as needed
   * Intermediate updates sent to user

4. **Response Delivery**
   * Final response formatted for platform
   * Egress layer sends message
   * State saved to database

### Tool Execution Pattern

```python theme={null}
# Example tool execution
async def send_email(to: str, subject: str, body: str):
    # 1. Validate inputs
    # 2. Load user's email credentials
    # 3. Send via Gmail/Outlook API
    # 4. Return execution status
    return ToolExecutionResponse(status="success", result="Email sent")
```

## Technology Stack

### Backend

* **Python 3.11+** - Core runtime
* **FastAPI** - Web framework
* **LangGraph** - Agent orchestration
* **Pydantic** - Data validation
* **Motor** - Async MongoDB driver

### AI & LLM

* **Portkey** - LLM gateway for routing
* **OpenAI** - Primary LLM provider
* **Google Gemini** - Alternative LLM provider
* **LangChain** - LLM abstractions and utilities

### Infrastructure

* **Docker** - Containerization
* **Kubernetes** - Orchestration
* **Azure Service Bus** - Message queue
* **Azure Cosmos DB** - Document database
* **Azure Key Vault** - Secrets management

### Web Automation

* **Playwright** - Browser automation
* **browser-use** - AI-powered browsing library
* **BeautifulSoup** - HTML parsing

## Design Principles

### Modularity

Each integration and tool is self-contained:

```
src/
  integrations/
    telegram/
      adapter.py      # Platform-specific logic
      handler.py      # Message handling
      sender.py       # Message sending
```

### Extensibility

Adding new integrations is straightforward:

1. Create new integration module
2. Implement base adapter interface
3. Register with tool factory
4. Configure credentials

### Scalability

* Stateless workers for horizontal scaling
* Queue-based architecture for load distribution
* Async operations throughout
* Efficient caching strategies

### Reliability

* Automatic retry logic for transient failures
* Dead letter queues for failed messages
* Health checks and monitoring
* Graceful degradation

## Configuration Management

### Environment-Based Config

```python theme={null}
# src/config/settings.py
class Settings:
    environment: str  # development, staging, production
    mongodb_uri: str
    azure_keyvault_url: str
    # ... more settings
```

### Secrets Management

Production secrets stored in Azure Key Vault:

* API tokens
* Database credentials
* Integration credentials

### Feature Flags

Enable/disable features per user:

* Beta feature access
* Tool availability
* Rate limiting

## Monitoring & Observability

### Logging

Structured logging throughout:

```python theme={null}
logger.info("Agent processing message", extra={
    "user_id": user_id,
    "platform": "telegram",
    "message_id": msg_id
})
```

### Metrics

Key metrics tracked:

* Message processing time
* Tool execution success rate
* Queue depth
* Error rates by type

### Tracing

Distributed tracing for request flows:

* End-to-end message journey
* Tool execution times
* External API calls

## Security

### Authentication

* Platform-specific auth (bot tokens, OAuth)
* User identity verification
* Session management

### Authorization

* User-level permissions
* Integration access control
* Tool usage policies

### Data Protection

* Encryption at rest (Cosmos DB)
* Encryption in transit (TLS)
* Credential isolation per user
* PII handling compliance

## Performance Considerations

### Caching Strategy

* User context cached in-memory (TTL: 5 min)
* Integration credentials cached (TTL: 1 hour)
* Common responses cached

### Resource Management

* Connection pooling for databases
* Rate limiting on external APIs
* Memory limits per worker
* Timeout handling for long operations

### Optimization

* Lazy loading of integrations
* Async/await throughout
* Bulk operations where possible
* Efficient serialization

## Future Enhancements

Planned architectural improvements:

* **Multi-tenant Support** - Isolated environments per organization
* **Plugin System** - User-installable tools and integrations
* **Event Streaming** - Real-time analytics with Kafka/Event Hub
* **Edge Deployment** - Regional workers for lower latency
* **GraphQL API** - Flexible data querying