CONTROL_PLANE_ARCHITECTURE.md

# =====================================================
# Apckeyl Framework
# CONTROL PLANE ARCHITECTURE
# Version 1.0
# =====================================================

# 1. Purpose

The Apckeyl Orchestrator is the central Control Plane
of the Apckeyl Framework.

The Orchestrator is responsible for coordination,
routing, task management, state tracking and communication
between independent processing modules.

The Orchestrator is NOT required to perform heavy
AI processing itself.

The framework therefore separates:

- Control Plane
- Compute Plane

This separation is a fundamental architectural principle
of the Apckeyl Framework.


# 2. Control Plane

The Control Plane contains the components responsible
for managing the system.

Primary responsibilities:

- receive tasks;
- validate tasks;
- create task records;
- assign task IDs;
- determine the required processing module;
- route tasks;
- monitor task state;
- handle errors;
- collect results;
- maintain logs;
- manage external Spaces and services;
- provide a unified interface for Telegram and other clients.


# 3. Compute Plane

The Compute Plane contains independent processing modules.

Compute modules perform the actual work.

Examples:

- Image Generation;
- Video Generation;
- Image Upscaler;
- Video Upscaler;
- Story Character Studio;
- Stock Factory;
- other AI processing services.

A Compute module should be independently replaceable.

The Orchestrator should not depend on the internal
implementation of a Compute module.


# 4. Core Principle

The fundamental relationship is:

    CONTROL PLANE
          |
          v
      ROUTING
          |
          v
     COMPUTE MODULE
          |
          v
        RESULT
          |
          v
    CONTROL PLANE


The Orchestrator controls the task.

The external module performs the task.


# 5. Orchestrator Responsibilities

The Orchestrator may contain:

- Orchestrator Core;
- Task Manager;
- Queue Manager;
- Space Manager;
- Download Manager;
- Logger;
- Resource Monitor;
- Module Registry;
- API Gateway;
- configuration management.


# 6. Compute Module Responsibilities

A Compute Module should:

1. receive a valid request;
2. process the request;
3. produce a result;
4. return a status;
5. return an error when processing fails.

The Compute Module should not need to know
how the entire Apckeyl Framework is organized.


# 7. First Compute Module

The first production Compute Module connected to
the Control Plane is:

    Apckeyl_RealESRGAN

Its purpose is image upscaling.

The existing Apckeyl_RealESRGAN Space remains an
independent processing Space.

It must NOT be replaced, deleted or moved as part
of the Control Plane migration.


# 8. Communication

The preferred communication model is:

    Client
      |
      v
    Orchestrator
      |
      v
    Compute Module
      |
      v
    Orchestrator
      |
      v
    Client


Possible clients include:

- Telegram Bot;
- future web interface;
- internal tools;
- other Apckeyl services.


# 9. Telegram Integration

The Telegram Bot is treated as a client of the
Control Plane.

The Telegram Bot should not contain the complete
processing architecture.

Instead:

    Telegram
       |
       v
    ApckeylBot
       |
       v
    Orchestrator
       |
       v
    Compute Module


This allows the Telegram interface to remain
independent from the processing modules.


# 10. Module Registry

The Orchestrator should maintain a registry of
available Compute Modules.

Conceptually:

    module_id
    module_name
    module_type
    endpoint
    status
    capabilities
    version


Example:

    module_id:
        realesrgan

    module_name:
        Apckeyl_RealESRGAN

    module_type:
        image_upscaler

    status:
        available


# 11. Task Routing

A task should contain enough information for the
Orchestrator to determine which module is required.

Example:

    task_type:
        image_upscale

The Orchestrator resolves:

    image_upscale
          |
          v
    realesrgan
          |
          v
    Apckeyl_RealESRGAN


# 12. Task Independence

Tasks must not depend on the physical location
of a Compute Module.

The Compute Module may later be:

- a Hugging Face Space;
- another cloud service;
- an API;
- a local service;
- another compatible processing backend.

The Control Plane should remain unchanged whenever
possible.


# 13. Replaceable Compute Modules

A Compute Module is replaceable.

For example:

    Apckeyl_RealESRGAN
            |
            v
    Image Upscaler Module A


can later become:

    Image Upscaler Module B


without redesigning the entire Orchestrator.


# 14. Failure Isolation

A failure of one Compute Module should not
automatically destroy the Control Plane.

Example:

    Apckeyl_RealESRGAN
           |
        ERROR
           |
           X

The Orchestrator should remain operational.

The task should receive a failed state and an
appropriate error description.


# 15. ZeroGPU Consideration

The current Hugging Face Orchestrator Space may operate
under ZeroGPU limitations.

Therefore the framework must NOT depend on the
Orchestrator Space having permanent CPU or GPU compute
capacity.

The Control Plane must remain lightweight.

Heavy processing should be delegated to Compute Modules.


# 16. Hardware Independence

The Apckeyl Framework must not depend on the user's
personal computer as a permanent server.

The user's computer is a development and administration
environment only.

The production architecture should remain operational
without the user's old laptop.


# 17. Existing Working Spaces

Existing working Spaces should be preserved.

In particular:

    Apckeyl_RealESRGAN

must remain an independent production module.

The Control Plane migration must not destroy or
rewrite existing working modules.


# 18. Future Architecture

The intended architecture is:

                         APCKEYL FRAMEWORK
                                |
                                v
                       +------------------+
                       |   CONTROL PLANE  |
                       |   ORCHESTRATOR   |
                       +--------+---------+
                                |
              +-----------------+-----------------+
              |                 |                 |
              v                 v                 v
       Image Factory      Video Factory      Stock Factory
              |                 |                 |
              v                 v                 v
        Image Modules      Video Modules      Stock Modules
              |
              v
      Apckeyl_RealESRGAN


# 19. Design Goal

The main design goal is:

    One Control Plane.
    Many independent Compute Modules.


The framework should allow new capabilities to be
added without rebuilding the entire system.


# 20. Development Strategy

Development should proceed incrementally.

Recommended order:

1. Control Plane architecture;
2. Orchestrator Core;
3. Module Registry;
4. Task Manager;
5. Space Manager;
6. communication layer;
7. first Compute Module integration;
8. Telegram integration;
9. additional Compute Modules;
10. Stock Factory;
11. Image Generation;
12. Video Generation;
13. Story Character Studio.


# 21. Architectural Rule

The following rule is mandatory:

    ORCHESTRATOR = CONTROL

    COMPUTE MODULE = WORK


The Orchestrator coordinates.

The Compute Module processes.

Neither component should unnecessarily assume
the responsibilities of the other.