Skip to main content

Architecture

Understanding the technical architecture of Imagor Studio.

System Overview​

Imagor Studio is built as a modern web application with a clear separation between backend and frontend:

Multi-Stage Docker Build​

Imagor Studio uses a sophisticated multi-stage Docker build process that creates an extremely lean final image by embedding the compiled frontend into the Go binary.

Build Process Details​

Stage 1: Web Builder (node:22-alpine)​

  • Purpose: Compile TypeScript/React frontend
  • Input: Source code from web/ directory
  • Process:
    1. Install npm dependencies
    2. Run Vite build process
    3. Output static assets to ../server/static
  • Output: Compiled HTML, CSS, JavaScript files

Stage 2: Server Builder (imagor-studio-builder)​

  • Purpose: Compile Go server with embedded frontend
  • Input: Go source code + static assets from Stage 1
  • Process:
    1. Download Go module dependencies
    2. Copy static assets from web builder
    3. Use Go's embed.FS to embed static files into binary
    4. Compile optimized Go binaries
  • Output: Self-contained binaries with embedded web assets

Stage 3: Runtime (debian:trixie-slim)​

  • Purpose: Minimal runtime environment
  • Input: Compiled binaries from Stage 2
  • Process:
    1. Install only essential runtime libraries
    2. Copy binaries and required shared libraries
    3. Configure unprivileged user
  • Output: Lean production image (~200MB)

Benefits of Multi-Stage Build​

  • 🪶 Lean Image Size: Final image contains only runtime essentials
  • 📦 Single Binary: Web assets embedded in Go binary via embed.FS
  • 🚀 Fast Startup: No separate web server needed
  • 🔒 Security: Minimal attack surface, unprivileged user
  • 📱 Portable: Self-contained deployment artifact

Server Architecture (Go)​

Core Components​

GraphQL API​

  • Framework: gqlgen
  • Purpose: Type-safe GraphQL server
  • Features:
    • Auto-generated resolvers
    • Schema-first development
    • Strong typing

Image Processing​

  • Engine: imagor
  • Library: libvips
  • Features:
    • High-performance image transformations
    • Memory-efficient streaming
    • Multi-format support
    • Video thumbnail generation (FFmpeg)

Authentication​

  • Method: JWT (JSON Web Tokens)
  • Features:
    • Stateless authentication
    • Configurable expiration
    • Secure token signing

Storage Abstraction​

  • Interface: Unified storage API
  • Implementations:
    • File storage (local filesystem)
    • S3 storage (AWS S3, MinIO, etc.)
  • Features:
    • Pluggable backends
    • Read-only access
    • Path-based organization

Configuration Management​

  • System: Multi-layered registry
  • Priority Order:

Encryption System​

Package Structure​

server/
├── cmd/                    # Entry points
│   ├── imagor-studio/     # Main application
│   └── imagor-studio-migrate/  # Migration tool
├── internal/              # Internal packages
│   ├── auth/             # Authentication
│   ├── config/           # Configuration
│   ├── database/         # Database connection
│   ├── encryption/       # Encryption utilities
│   ├── httphandler/      # HTTP handlers
│   ├── imagorprovider/   # Imagor integration
│   ├── middleware/       # HTTP middleware
│   ├── migrations/       # Database migrations
│   ├── model/            # Data models
│   ├── resolver/         # GraphQL resolvers
│   ├── storage/          # Storage backends
│   └── storageprovider/  # Storage factory
└── static/               # Embedded web assets (from build)

Web Architecture (React)​

Technology Stack​

  • Build Tool: Vite
  • Language: TypeScript
  • Styling: Tailwind CSS
  • Router: TanStack Router (type-safe)
  • UI Components: shadcn/ui
  • State Management: Custom store with React integration
  • GraphQL Client: graphql-request with code generation

Key Features​

Virtual Scrolling​

  • Efficient rendering of large image galleries
  • Smooth scrolling performance
  • Dynamic loading and unloading

Live Image Editing​

  • Real-time preview
  • Non-destructive transformations
  • URL-based image manipulation
  • Instant URL generation

Touch Optimization​

  • Mobile-first design
  • Touch gestures support
  • Responsive layouts
  • Progressive enhancement

Component Architecture​

web/src/
├── api/                  # API clients
├── components/           # React components
│   ├── ui/              # Base UI components
│   ├── image-gallery/   # Gallery components
│   ├── image-editor/    # Editor components
│   └── folder-tree/     # File browser
├── pages/               # Route pages
├── stores/              # State management
├── hooks/               # Custom React hooks
├── loaders/             # Data loaders
└── graphql/             # GraphQL queries

Data Flow​

Image Editing Flow​

Security Architecture​

Authentication Flow​

Encryption Flow​

Deployment Architecture​

Single Instance​

Multi-Instance (Production)​

Performance Considerations​

Image Processing​

  • libvips: Streaming processing for memory efficiency
  • Multi-threading: Parallel processing on multi-core systems
  • Format optimization: Automatic format selection (WebP, AVIF)

Database​

  • Connection pooling: Efficient database connections
  • Indexed queries: Fast data retrieval
  • Migration system: Safe schema updates

Frontend​

  • Code splitting: Lazy loading of routes
  • Virtual scrolling: Efficient rendering
  • Image lazy loading: Load images on demand
  • Caching: Browser and CDN caching

Scalability​

Horizontal Scaling​

  • Stateless application design
  • Shared database backend
  • Shared storage backend
  • Load balancer compatible

Vertical Scaling​

  • Multi-core CPU utilization
  • Memory-efficient processing
  • Configurable resource limits

Build Optimization​

The multi-stage Docker build process ensures optimal deployment:

  1. Development Dependencies Excluded: Node.js, TypeScript compiler, and build tools are not in the final image
  2. Static Asset Embedding: Frontend assets are compiled into the Go binary using embed.FS
  3. Minimal Runtime: Only essential libraries for libvips and FFmpeg are included
  4. Layer Optimization: Docker layers are optimized for caching and minimal size
  5. Security: Runs as unprivileged user with minimal attack surface

This results in a production image that's approximately 200MB compared to what would be 1GB+ with traditional approaches.

Next Steps​