0 introduction

@CKIR.IO/VISIONS: An AI-Powered Vision Analysis Microservice

Abstract

This wiki documents the design, implementation, and operational characteristics of @CKIR.IO/VISIONS, a NestJS-based microservice monorepo for image analysis using locally-hosted Ollama vision models. The system exposes two primary ingress protocols—a RESTful multipart API and a Model Context Protocol (MCP) JSON-RPC 2.0 endpoint—unified under a single Fastify HTTP server augmented with a Socket.IO real-time transport layer. Asynchronous job execution is delegated to BullMQ workers backed by Redis/KeyDB; image preprocessing is performed within the worker by the Sharp pipeline before Ollama inference. The project demonstrates that generative coding workflows, while accelerating exploration, require a disciplined remediation cycle—owning the code—before production deployment.

System Overview

flowchart TB
    subgraph ClientLayer["Client Layer"]
        Dashboard[Vue 3 Dashboard UI]
        RestClient[REST Client]
        MCPClient[MCP Client<br/>Claude Desktop, etc.]
    end

    subgraph APILayer["API Layer (Fastify / Port 3000)"]
        Gateway[Fastify Gateway]
        ClassicCtrl[ClassicController<br/>/api/v1/vision]
        JsonRpcCtrl[JsonRpcController<br/>/api/v1/mcp]
        HealthCtrl[HealthController<br/>/api/v1/health]
    end

    subgraph ServiceLayer["Service Layer"]
        VisionService[AnalyzeImageService]
        RpcService[JsonRpcService]
        HealthService[HealthService]
        SocketService[SocketService]
    end

    subgraph QueueLayer["Queue Layer"]
        BullMQ[(BullMQ / KeyDB)]
        Q1[image-describe Queue]
        Q2[image-compare Queue]
        Q3[image-ocr Queue]
    end

    subgraph WorkerLayer["Worker Layer"]
        DescProc[VisionsDescribeProcessor]
        CompProc[VisionsCompareProcessor]
        OCRProc[VisionsOCRProcessor]
        Preproc[ImagePreprocessingService]
    end

    subgraph Infrastructure["Infrastructure"]
        Ollama[Ollama Server<br/>Port 11434]
        KeyDB[KeyDB<br/>Port 6379]
        SocketIO[Socket.IO<br/>Port 3000]
    end

    Dashboard --> Gateway
    RestClient --> ClassicCtrl
    MCPClient --> JsonRpcCtrl

    ClassicCtrl --> VisionService
    JsonRpcCtrl --> RpcService
    HealthCtrl --> HealthService

    VisionService --> BullMQ
    RpcService --> BullMQ

    BullMQ --> Q1 --> DescProc --> Preproc --> Ollama
    BullMQ --> Q2 --> CompProc --> Preproc --> Ollama
    BullMQ --> Q3 --> OCRProc --> Preproc --> Ollama

    DescProc --> SocketIO --> Dashboard
    CompProc --> SocketIO --> RestClient
    OCRProc --> SocketIO --> MCPClient

    BullMQ --> KeyDB

Loading

Communication Patterns

Pattern	Protocol	Use Case
Synchronous (HTTP)	REST / JSON-RPC	Request submission, health checks, model listing, job cancellation
Asynchronous (Queue)	BullMQ / Redis	Image processing, AI inference, result preparation
Real-time (WebSocket)	Socket.IO	Streaming status, progressive token delivery, final result dispatch

Documentation Index

Getting Started

• 0.1. Quick Start

Server Architecture

• 1. Server Overview
• 1.1. REST Interfaces
• 1.2. MCP Interfaces
• 1.3. BullMQ Async Processing
• 1.4. Socket.IO Real-time Layer
• 1.5. Image Preprocessing Pipeline

Dashboard

• 2. Dashboard Overview
• 2.1. Frontend Architecture
• 2.2. Color Harmony & Theming
• 2.3. State Management & Real-time Events

Methodology

• 3. AI-Assisted Development: Vibe Coding, Context Coding, and Code Ownership
• 3.1. Market Positioning & Competitive Landscape

Quick Start

For a step-by-step Docker Compose setup, see 0.1 Quick Start.

Technology Matrix

Domain	Technology	Role
Backend Runtime	Node.js 18+	Server-side TypeScript execution (ES module mode)
Framework	NestJS (Fastify adapter)	Dependency-injected modular architecture
HTTP Server	Fastify	High-throughput, low-latency request handling
Job Queue	BullMQ	Async task scheduling and worker orchestration
Real-time	Socket.IO (Redis adapter)	Cross-server event broadcasting
AI Backend	Ollama	Local LLM inference with vision model support
Image Processing	Sharp (libvips)	Grayscale, resize, sharpen, Gaussian blur, CLAHE
Frontend	Vue 3 Composition API	Declarative UI with reactive state
Bundler	Vite 5	Fast HMR and optimized production builds
Styling	Tailwind CSS v4	Utility-first CSS with CSS custom properties
State	Pinia	Type-safe reactive store management
Queries	TanStack Vue Query	Server-state synchronization and caching

---

This project demonstrates the tension between generative coding velocity and software engineering discipline, explored in detail in Section 3.