Skip to content

Squirrel Backend

High-performance Python FastAPI backend for EPICS control system snapshot/restore operations, designed to handle 40-50K PVs efficiently.

Features

  • Distributed Architecture - Separate processes for API, PV monitoring, and background tasks
  • Fast Snapshot Creation - Parallel EPICS reads or instant Redis cache reads (<5s for 40K PVs)
  • Efficient Restore Operations - Parallel EPICS writes for quick machine state restoration
  • Real-Time Updates - WebSocket streaming with diff-based updates and multi-instance support
  • Tag-based Organization - Group and categorize PVs using hierarchical tags
  • Snapshot Comparison - Compare two snapshots with tolerance-based diff
  • Persistent Job Queue - Background tasks survive restarts with automatic retries
  • Circuit Breaker - Fail-fast protection against unresponsive IOCs
  • PostgreSQL Storage - Reliable relational database with async support

Technology Stack

Component Technology
Language Python 3.11+
Framework FastAPI
Database PostgreSQL 16+
ORM SQLAlchemy 2.0 (async)
Cache/Queue Redis 7+
Task Queue Arq
EPICS aioca (async Channel Access)
Migrations Alembic
Validation Pydantic v2

Architecture Overview

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   API Server    │     │   PV Monitor    │     │   Arq Worker    │
│  (squirrel-api) │     │(squirrel-monitor)│    │(squirrel-worker)│
│  REST/WebSocket │     │  EPICS → Redis  │     │  Snapshot jobs  │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌────────────┴────────────┐
                    ▼                         ▼
            ┌─────────────┐           ┌─────────────┐
            │    Redis    │           │  PostgreSQL │
            │ Cache/Queue │           │   Storage   │
            └─────────────┘           └─────────────┘
                    │
                    ▼
            ┌─────────────┐
            │  EPICS IOCs │
            │  40-50K PVs │
            └─────────────┘

  • Getting Started

    Get up and running in 2 minutes with Docker Compose

    Quick Start

  • Configuration

    Environment variables and deployment options

    Configuration

  • Architecture

    System design and component overview

    Architecture

  • API Reference

    REST endpoints and WebSocket documentation

    API Reference

What's Running?

When you start Squirrel Backend with Docker Compose, you get:

Service Port Description
squirrel-api 8080 REST/WebSocket API server
squirrel-db 5432 PostgreSQL database
squirrel-redis 6379 Redis cache/queue
squirrel-monitor - EPICS PV monitoring service
squirrel-worker-1/2 - Background job processors

License

MIT License - See LICENSE for details.