proserve 2.0.1

Professional Service Framework - Revolutionary modular microservice framework with zero-config API

🚀 ProServe - Modern Microservices Framework

Build production-ready microservices with minimal code - Python decorators or YAML manifests!

🎯 98% Less Boilerplate • 5-Minute Start • Production Ready

ProServe is a revolutionary microservices framework that combines the simplicity of Flask with the power of modern architecture. Create APIs, static sites, real-time chat, and more with just a few lines of code.

🚀 Fully Modular Architecture: All components are now modular, testable, and follow SOLID principles
🧪 Comprehensive E2E Testing: 8+ test suites covering real-world scenarios, security, performance, and integrations

⚡ Quick Start (3 Lines of Code!)

# app.py
from proserve import Service

app = Service("my-api")

@app.endpoint("/", method="GET")
async def hello(request):
    return {"message": "Hello World! 🚀"}

if __name__ == "__main__":
    app.run(port=8080)

python app.py
# Open: http://localhost:8080

That's it! You have a production-ready API running.

🎓 New to microservices? Check out our Junior Quick Start Guide - "ProServe in 5 minutes"

🏗️ Architecture

ProServe Ecosystem Integration

graph TB
    subgraph "Modular Ecosystem"
        ProServe[ProServe Framework<br/>Core Microservices]
        Servos[Servos<br/>Environment Isolation]
        EDPMT[EDPMT Framework<br/>Hardware Control]
        wmlog[wmlog<br/>Centralized Logging]
    end
    
    ProServe --> Servos
    ProServe --> wmlog
    EDPMT --> ProServe
    Servos --> Docker[Docker Containers]
    wmlog --> Monitoring[Real-time Monitoring]
    
    subgraph "ProServe Core Architecture"
        ServiceAPI[Service API<br/>Zero-Config Decorators]
        ManifestEngine[Manifest Engine<br/>YAML-Driven Config]
        ServiceRunner[Service Runner<br/>Multi-Environment]
        Discovery[Discovery & Migration<br/>Auto-Detection]
    end
    
    ProServe --> ServiceAPI
    ProServe --> ManifestEngine
    ProServe --> ServiceRunner
    ProServe --> Discovery
    
    subgraph "Deployment Targets"
        Cloud[Cloud Native<br/>Docker/K8s]
        Embedded[Embedded Systems<br/>MicroPython/Arduino]
        Edge[Edge Computing<br/>RP2040/ESP32]
        Local[Local Development<br/>Process Isolation]
    end
    
    ServiceRunner --> Cloud
    ServiceRunner --> Embedded
    ServiceRunner --> Edge
    ServiceRunner --> Local
    
    subgraph "Service Features"
        HTTP[HTTP Endpoints]
        WebSocket[WebSocket Handlers]
        Background[Background Tasks]
        Monitoring[Health & Metrics]
        StaticFiles[Static File Serving]
        CORS[CORS & Security]
    end
    
    ServiceAPI --> HTTP
    ServiceAPI --> WebSocket
    ServiceAPI --> Background
    ServiceAPI --> Monitoring
    ServiceAPI --> StaticFiles
    ServiceAPI --> CORS

Detailed ProServe Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                            ProServe Framework                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │                      Developer Interface                            │     │
│  │                                                                     │     │
│  │  ┌────────────────┐        ┌─────────────────────────────────────┐   │     │
│  │  │  Zero-Config   │        │      Manifest-Based                │   │     │
│  │  │   Decorators   │        │      Configuration                  │   │     │
│  │  │                │        │                                     │   │     │
│  │  │ @service.      │        │  name: my-service                   │   │     │
│  │  │  endpoint()    │        │  version: 1.0.0                     │   │     │
│  │  │ @service.      │        │  type: http                         │   │     │
│  │  │  websocket()   │        │  port: 8080                         │   │     │
│  │  │ @service.      │        │  isolation:                         │   │     │
│  │  │  background()  │        │    mode: docker                     │   │     │
│  │  └────────────────┘        └─────────────────────────────────────┘   │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
│                                │                                             │
│                                ▼                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │                      Core Framework                                │     │
│  │                                                                     │     │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐  │     │
│  │  │   Service   │ │  Manifest   │ │   Runner    │ │    Discovery    │  │     │
│  │  │     API     │ │   Engine    │ │             │ │   & Migration   │  │     │
│  │  │             │ │             │ │             │ │                 │  │     │
│  │  │• Endpoints  │ │• YAML Parse │ │• Multi-Env  │ │• Auto-Detect    │  │     │
│  │  │• WebSocket  │ │• Validation │ │• Process    │ │• Blue-Green     │  │     │
│  │  │• Background │ │• Env Vars   │ │• Docker     │ │• Gradual        │  │     │
│  │  │• Health     │ │• Templates  │ │• K8s        │ │  Migration      │  │     │
│  │  │• Metrics    │ │• Inheritance│ │• MicroPy    │ │• Rollback       │  │     │
│  │  │• CORS       │ │• Includes   │ │• Arduino    │ │• Monitor        │  │     │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘  │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
│                                │                                             │
│                                ▼                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │                   Integration Layer                                │     │
│  │                                                                     │     │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐  │     │
│  │  │   Servos    │ │   wmlog     │ │   aiohttp   │ │      EDPMT      │  │     │
│  │  │ Isolation   │ │  Logging    │ │   Server    │ │   Framework     │  │     │
│  │  │             │ │             │ │             │ │                 │  │     │
│  │  │• Process    │ │• Structured │ │• Async      │ │• Hardware       │  │     │
│  │  │• Docker     │ │• Real-time  │ │• HTTP/WS    │ │• Manifest       │  │     │
│  │  │• Platform   │ │• Broadcasting│ │• CORS       │ │• Service        │  │     │
│  │  │  Detection  │ │• Context    │ │• Static     │ │  Templates      │  │     │
│  │  │• Resource   │ │  Enrichment │ │  Files      │ │• Device         │  │     │
│  │  │  Limits     │ │• Multi-dest │ │• Middleware │ │  Management     │  │     │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘  │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
│                                │                                             │
│                                ▼                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │                  Deployment Environments                           │     │
│  │                                                                     │     │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐  │     │
│  │  │    Cloud    │ │  Embedded   │ │    Edge     │ │      Local      │  │     │
│  │  │   Native    │ │   Systems   │ │  Computing  │ │  Development    │  │     │
│  │  │             │ │             │ │             │ │                 │  │     │
│  │  │• Docker     │ │• MicroPython│ │• RP2040     │ │• Process        │  │     │
│  │  │• Kubernetes │ │• CircuitPy  │ │• ESP32      │ │• Thread         │  │     │
│  │  │• Compose    │ │• Arduino    │ │• STM32      │ │• Debug          │  │     │
│  │  │• Swarm      │ │• PlatformIO │ │• Bare Metal │ │• Hot Reload     │  │     │
│  │  │• Scaling    │ │• RTOS       │ │• Real-time  │ │• Live Logs      │  │     │
│  │  │• Load Bal   │ │• Low Power  │ │• IoT        │ │• Rich Console   │  │     │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘  │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘

✨ Features

🎯 Core Framework

• Manifest-Driven Architecture: Declarative YAML-based service configuration
• Multi-Environment Isolation: Process, Docker, Kubernetes, MicroPython, Arduino, RP2040
• Auto-Discovery & Migration: Automatic service detection and seamless migration tools
• Zero Vendor Lock-in: Export generated code and run independently

🔧 Advanced Capabilities

• Structured Logging: Rich console output with JSON export and WebSocket broadcasting
• Health & Metrics: Built-in monitoring endpoints with Prometheus integration
• Dynamic Handlers: Hot-reload Python scripts with isolation sandboxing
• Background Tasks: Async periodic tasks with optional WebSocket broadcasting
• CORS & Security: Configurable CORS, authentication, and request validation

🌍 Multi-Platform Support

• Cloud Native: Docker, Kubernetes, Docker Compose orchestration
• Embedded Systems: MicroPython, CircuitPython, Arduino IDE integration
• Hardware Platforms: Raspberry Pi Pico (RP2040), ESP32, STM32, Arduino boards
• Development Tools: PlatformIO, Arduino CLI, esptool integration

🚀 DevOps & Deployment

• Blue-Green Migration: Gradual traffic shifting with automatic rollback
• Service Discovery: Automatic manifest generation from existing code
• Monitoring Stack: Grafana dashboards, Prometheus metrics, Alertmanager
• CI/CD Ready: GitHub Actions, Docker builds, PyPI publishing

📦 Installation

Basic Installation

pip install proserve

With All Features

pip install proserve[all]

Specific Feature Sets

# Docker & Kubernetes support
pip install proserve[docker,kubernetes]

# MicroPython & Embedded development
pip install proserve[micropython,arduino,rp2040]

# Monitoring & observability
pip install proserve[monitoring]

# Development tools
pip install proserve[development,testing]

🚀 Quick Start

🎯 NEW: Simplified Decorator API (No Manifest Required!)

# app.py - Zero configuration needed!
from proserve import Service

service = Service(name="my-service")

@service.endpoint("/api/hello", method="GET")
async def hello(request):
    return {"message": "Hello, ProServe!"}

@service.websocket("/ws")
async def websocket_handler(ws):
    async for message in ws:
        await ws.send(f"Echo: {message}")

@service.background_task(interval=60)
async def cleanup():
    print("Running cleanup...")

# Start the service
if __name__ == "__main__":
    service.run(port=8080)

Run it:

python app.py
# 🚀 Service running at http://localhost:8080
# 📊 Health check: http://localhost:8080/health
# 📈 Metrics: http://localhost:8080/metrics

📋 Traditional: Manifest-Based Configuration

# my-service.yaml
name: my-awesome-service
version: 1.0.0
type: http
port: 8080
host: 0.0.0.0

# Features
requires_edpmt: false
enable_cors: true
enable_health: true
enable_metrics: true

# Endpoints
endpoints:
  - path: /api/hello
    method: GET
    script: handlers/hello.py

# WebSocket handlers
websocket_handlers:
  - path: /ws
    script: handlers/websocket.py

# Background tasks
background_tasks:
  - script: handlers/background.py
    interval: 60
    broadcast: true

# Environment isolation
isolation:
  mode: process  # none, process, docker, kubernetes, micropython, arduino
  timeout: 30
  auto_environment: true

# Environment variables
env_vars:
  - API_KEY
  - DATABASE_URL
  - DEBUG

# Static file serving
static_dirs:
  "/static": "./static"
  "/assets": "./assets"

2. Create Handler Scripts

# handlers/hello.py
async def handle_request(request, service):
    return {"message": "Hello from ProServe!", "service": service.manifest.name}

# handlers/websocket.py  
async def handle_websocket(ws, data, service):
    if data.get('action') == 'ping':
        return {'action': 'pong', 'timestamp': time.time()}

# handlers/background.py
async def background_task(service):
    service.logger.info("Background task executed")
    return {"status": "completed"}

3. Run Your Service

# Using CLI
proserve run --manifest my-service.yaml

# Using Python
python -c "
from proserve import ServiceRunner
runner = ServiceRunner('my-service.yaml')
runner.run()
"

🌍 Multi-Environment Deployment

Cloud Native (Docker/Kubernetes)

isolation:
  mode: docker
  image: python:3.11-slim
  resources:
    memory: "512Mi"
    cpu: "0.5"

MicroPython (RP2040/ESP32)

isolation:
  mode: micropython
  platform: rp2040  # or esp32, esp8266
  firmware_version: "1.19.1"
  memory_limit: 256KB

Arduino

isolation:
  mode: arduino
  board: esp32dev  # or nano33iot, uno_r4_wifi
  libraries:
    - WiFi
    - ArduinoJson
    - PubSubClient

🔧 Service Discovery & Migration

Discover Existing Services

# Automatic service discovery
proserve-discover --project-root . --output manifests/

# Generate manifests from existing code
proserve convert legacy-service.py --output service.yaml

Migrate to Manifest-Based

# Start migration with blue-green deployment  
proserve-migrate migrate --service my-service --strategy blue-green

# Monitor migration progress
proserve-migrate status --service my-service

# Complete migration
proserve-migrate complete --service my-service

🐳 Docker & Orchestration

Docker Compose

# docker-compose.yml
version: '3.8'
services:
  my-service:
    image: proserve:latest
    environment:
      - PROSERVE_MANIFEST=/app/my-service.yaml
    ports:
      - "8080:8080"
    volumes:
      - ./manifests:/app/manifests:ro

Multiple Architectures

# Build for different platforms
make build-docker  # Builds arm64, x86_64, micropython, arduino

# Deploy to specific environment
proserve-deploy --environment production --platform kubernetes

📊 Monitoring & Observability

Built-in Endpoints

• GET /health - Health check with service status
• GET /metrics - Prometheus metrics endpoint
• GET /status - Detailed service information
• WS /logs - Real-time log streaming

Prometheus Integration

# Automatic metrics collection
monitoring:
  prometheus: true
  metrics_port: 9090
  custom_metrics:
    - request_duration_seconds
    - background_task_duration
    - websocket_connections_total

Grafana Dashboards

# Setup monitoring stack
docker-compose -f docker-compose.manifest.yml --profile monitoring up
# Access Grafana at http://localhost:3000 (admin/admin123)

🧪 Testing & Development

Run Tests

make test              # All tests
make test-unit         # Unit tests only  
make test-integration  # Integration tests
make test-environments # Multi-environment tests

Development Setup

make dev-setup         # Complete dev environment
make format           # Code formatting
make lint             # Code linting
make check            # All quality checks

📚 Examples

Simple HTTP Service

from proserve import ProServeService, Manifest

manifest = Manifest.from_yaml("service.yaml")
service = ProServeService(manifest)

@service.endpoint("/api/users", methods=["GET"])
async def get_users(request):
    return {"users": ["alice", "bob"]}

service.run()

MicroPython IoT Service

# For RP2040/ESP32
from proserve.embedded import MicroPythonService

service = MicroPythonService("iot-sensor.yaml")

@service.background_task(interval=30)
async def read_sensors():
    temperature = sensor.read_temperature()
    service.broadcast({"temperature": temperature})

service.run()

📚 Learning Path & Examples

🎓 NEW: Progressive Learning Examples

We've created a complete learning path from absolute beginner to production deployment:

Level	Example	Time	Skills
👶 Junior	01-hello-world	5 min	First API (3 lines!)
	02-static-website	10 min	Static files + manifest
	03-simple-api	15 min	REST endpoints
	04-manifest-driven	20 min	YAML-only API
🧑‍💻 Mid	05-database-api	30 min	SQLite + ORM patterns
	06-auth-middleware	45 min	JWT + RBAC
	07-file-upload	30 min	File handling + security
	08-websocket-chat	45 min	Real-time WebSocket chat

🚀 Quick Start Paths

Complete Beginner (never built APIs):

cd examples/01-hello-world && python app.py

Know Docker/Flask (familiar with web development):

cd examples/03-simple-api && python app.py  

Prefer Configuration (like docker-compose users):

cd examples/04-manifest-driven && proserve run

📖 Documentation

• 🎓 Junior Quick Start - "ProServe in 5 minutes" for beginners
• 🌐 Ecosystem Guide - Complete ecosystem overview with diagrams
• 📚 Examples Guide - Progressive examples with learning path
• API Reference - Detailed API documentation
• Migration Guide - Legacy service migration
• Deployment Guide - Production deployment

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

git clone https://github.com/proserve/proserve.git
cd proserve
make dev-setup
make test

📄 License

This project is licensed under the Apache License 2.0 - see LICENSE file for details.

👨‍💻 Author

Tom Sapletta

• Email: [e-mail]
• GitHub: @tom-sapletta-com
• Website: softreck.dev

🏆 Credits

ProServe is built on top of excellent open-source libraries:

• aiohttp - Async HTTP framework
• structlog - Structured logging
• rich - Beautiful terminal output
• docker-py - Docker Python SDK
• PyYAML - YAML processing

---

Made with ❤️ by the ProServe Team