Skip to main content

Code Structure

Understanding the Pixell codebase organization and architecture.

Note: This documentation is generated by AI based on the source code, and therefore it may have some incorrect knowledge of the project. In that case, please contact engineering@pixell.global

Overview​

The Pixell project is organized into several main components, each with its own repository and specific responsibilities. This document provides an overview of the codebase structure and how the different components interact.

Repository Structure​

pixell/
├── pak/                    # Pixell Agent Kit
├── par/                     # Pixell Agent Runtime
├── pac/                     # Pixell Agent Cloud
├── paf-core/               # Pixell Agent Framework Core
├── docs/                   # Documentation
├── examples/               # Example agents and applications
├── tools/                  # Development tools and utilities
└── tests/                  # Integration and end-to-end tests

Component Architecture​

PAK (Pixell Agent Kit)​

Repository: pak/
Purpose: Development toolkit for building and packaging agents

Structure​

pak/
├── src/                    # Source code
│   ├── cli/               # Command-line interface
│   ├── build/             # Build system
│   ├── templates/         # Agent templates
│   ├── validation/        # Package validation
│   └── utils/             # Utility functions
├── templates/             # Agent templates
│   ├── basic/             # Basic agent template
│   ├── advanced/          # Advanced agent template
│   └── minimal/           # Minimal agent template
├── tests/                 # Test files
├── docs/                  # PAK-specific documentation
└── examples/              # Example agents

Key Components​

  • CLI Interface (src/cli/) - Command-line tools for agent development
  • Build System (src/build/) - Packaging and building agents
  • Templates (templates/) - Pre-built agent templates
  • Validation (src/validation/) - Package and configuration validation

Dependencies​

# Core dependencies
fastapi>=0.68.0
uvicorn>=0.15.0
pydantic>=1.8.0
click>=8.0.0
pyyaml>=6.0
jinja2>=3.0.0

# Development dependencies
pytest>=6.0.0
black>=21.0.0
flake8>=3.8.0
mypy>=0.910

PAR (Pixell Agent Runtime)​

Repository: par/
Purpose: Runtime environment for executing agents

Structure​

par/
├── src/                    # Source code
│   ├── runtime/           # Runtime core
│   ├── api/               # REST API
│   ├── a2a/               # Agent-to-agent communication
│   ├── gateway/           # API gateway
│   ├── monitoring/        # Monitoring and metrics
│   ├── security/          # Security features
│   └── storage/           # Storage management
├── config/                # Configuration files
├── docker/                # Docker configurations
├── k8s/                   # Kubernetes manifests
├── tests/                 # Test files
└── docs/                  # PAR-specific documentation

Key Components​

  • Runtime Core (src/runtime/) - Core runtime functionality
  • API Gateway (src/gateway/) - Request routing and load balancing
  • A2A Communication (src/a2a/) - Agent-to-agent communication
  • Monitoring (src/monitoring/) - Metrics, logging, and tracing
  • Security (src/security/) - Authentication and authorization

Dependencies​

# Core dependencies
fastapi>=0.68.0
uvicorn>=0.15.0
grpcio>=1.40.0
grpcio-tools>=1.40.0
redis>=3.5.0
sqlalchemy>=1.4.0
alembic>=1.6.0

# Monitoring
prometheus-client>=0.11.0
opentelemetry-api>=1.0.0
jaeger-client>=4.8.0

# Security
python-jose>=3.2.0
passlib>=1.7.4
bcrypt>=3.2.0

PAC (Pixell Agent Cloud)​

Repository: pac/
Purpose: Cloud platform for managing agents

Structure​

pac/
├── src/                    # Source code
│   ├── api/               # REST API
│   ├── web/               # Web interface
│   ├── auth/              # Authentication
│   ├── billing/           # Billing and usage
│   ├── deployment/        # Agent deployment
│   └── monitoring/        # Cloud monitoring
├── frontend/              # Frontend application
│   ├── src/               # React/Vue source
│   ├── public/            # Static assets
│   └── dist/              # Built assets
├── infrastructure/        # Infrastructure as code
│   ├── terraform/         # Terraform configurations
│   ├── helm/              # Helm charts
│   └── docker/            # Docker configurations
├── tests/                 # Test files
└── docs/                  # PAC-specific documentation

Key Components​

  • API (src/api/) - REST API for cloud services
  • Web Interface (src/web/, frontend/) - User interface
  • Authentication (src/auth/) - User authentication and authorization
  • Billing (src/billing/) - Usage tracking and billing
  • Deployment (src/deployment/) - Agent deployment management

PAF-Core (Pixell Agent Framework Core)​

Repository: paf-core/
Purpose: Core framework and shared libraries

Structure​

paf-core/
├── src/                    # Source code
│   ├── core/              # Core framework
│   ├── protocols/         # Communication protocols
│   ├── serialization/     # Data serialization
│   ├── security/          # Security primitives
│   ├── monitoring/        # Monitoring utilities
│   └── utils/             # Utility functions
├── proto/                 # Protocol buffer definitions
├── tests/                 # Test files
└── docs/                  # PAF-Core documentation

Key Components​

  • Core Framework (src/core/) - Base classes and interfaces
  • Protocols (src/protocols/) - Communication protocols
  • Serialization (src/serialization/) - Data serialization
  • Security (src/security/) - Security primitives
  • Monitoring (src/monitoring/) - Monitoring utilities

Shared Libraries​

Common Dependencies​

All components share common dependencies for consistency:

# Core dependencies
pydantic>=1.8.0
structlog>=21.0.0
tenacity>=8.0.0
httpx>=0.24.0

# Testing
pytest>=6.0.0
pytest-asyncio>=0.18.0
pytest-cov>=2.12.0
pytest-mock>=3.6.0

# Development
black>=21.0.0
flake8>=3.8.0
mypy>=0.910
pre-commit>=2.15.0

Shared Utilities​

  • Logging - Structured logging with structlog
  • Configuration - Configuration management with pydantic
  • HTTP Client - HTTP client with httpx
  • Retry Logic - Retry mechanisms with tenacity

Development Tools​

Build System​

# Build all components
make build

# Build specific component
make build-pak
make build-par
make build-pac
make build-paf-core

# Run tests
make test

# Run linting
make lint

# Run type checking
make type-check

Docker Development​

# Start development environment
docker-compose up -d

# Run specific service
docker-compose up par

# View logs
docker-compose logs -f par

Testing​

# Run all tests
pytest

# Run specific test file
pytest tests/test_agent.py

# Run with coverage
pytest --cov=src tests/

# Run integration tests
pytest tests/integration/

Code Organization Principles​

1. Separation of Concerns​

Each component has a clear, single responsibility:

  • PAK: Agent development and packaging
  • PAR: Agent execution and runtime
  • PAC: Cloud management and deployment
  • PAF-Core: Shared framework and utilities

2. Modular Design​

Components are designed to be modular and loosely coupled:

  • Clear interfaces between components
  • Minimal dependencies between components
  • Easy to test and maintain

3. Consistent Structure​

All components follow the same structure:

  • src/ - Source code
  • tests/ - Test files
  • docs/ - Documentation
  • config/ - Configuration files

4. API-First Design​

All components expose well-defined APIs:

  • REST APIs for HTTP communication
  • gRPC APIs for high-performance communication
  • Clear API documentation

Data Flow​

Configuration Management​

Environment-Specific Configs​

# Development
development:
  debug: true
  log_level: debug
  database: sqlite:///dev.db

# Staging
staging:
  debug: false
  log_level: info
  database: postgresql://staging.db

# Production
production:
  debug: false
  log_level: warn
  database: postgresql://prod.db

Configuration Hierarchy​

  1. Default values - Hardcoded defaults
  2. Environment variables - Override defaults
  3. Configuration files - Override environment variables
  4. Command-line arguments - Override all others

Security Considerations​

Authentication and Authorization​

  • JWT tokens for API authentication
  • RBAC for role-based access control
  • API keys for service-to-service communication
  • OAuth2 for third-party integrations

Data Protection​

  • Encryption at rest for sensitive data
  • TLS/SSL for data in transit
  • Secrets management for credentials
  • Audit logging for security events

Monitoring and Observability​

Metrics​

  • Prometheus for metrics collection
  • Grafana for metrics visualization
  • Custom metrics for business logic

Logging​

  • Structured logging with JSON format
  • Log aggregation with ELK stack
  • Log levels for different environments

Tracing​

  • Distributed tracing with Jaeger
  • Request correlation across services
  • Performance monitoring

Performance Considerations​

Scalability​

  • Horizontal scaling with load balancers
  • Database sharding for large datasets
  • Caching with Redis
  • CDN for static assets

Optimization​

  • Connection pooling for databases
  • Async/await for I/O operations
  • Compression for network traffic
  • Resource limits for containers

Testing Strategy​

Unit Tests​

  • Component isolation - Test individual components
  • Mock dependencies - Mock external services
  • High coverage - Aim for >90% coverage
  • Fast execution - Run in less than 1 second

Integration Tests​

  • Component interaction - Test component integration
  • Real dependencies - Use real services in tests
  • End-to-end scenarios - Test complete workflows
  • Database transactions - Test with real databases

Performance Tests​

  • Load testing - Test under high load
  • Stress testing - Test beyond normal capacity
  • Memory profiling - Identify memory leaks
  • CPU profiling - Identify performance bottlenecks

Deployment Architecture​

Development​

Staging​

Production​

Next Steps​

After understanding the code structure:

  1. Build from Source - Set up your development environment
  2. How to Contribute - Start contributing to the project
  3. Roadmap - See what features are planned
  4. Choose a component - Pick a component to work on
  5. Start coding - Make your first contribution!

Ready to explore the codebase? Check out Build from Source to set up your development environment!