XC_VM/docs/en/development/architecture.md

Architecture Overview

Project type

Structured PHP monolith with a modular extension layer.

• No DDD, no Hexagonal, no Clean Architecture — intentional.
• Split by context with minimal abstractions: Controller → Service → Repository.
• Two build artifacts from one codebase: MAIN (full panel) and LB (load balancer subset).

---

Source tree

Path	Role
src/core/	Infrastructure primitives: DI container, events, HTTP, config, auth, logging
src/domain/	Business contexts: Stream, VOD, Line, User, Server, Security, etc.
src/modules/	Optional extension layer — loaded by ModuleLoader
src/public/	Front controller, router, controllers, views, assets
src/cli/	Console commands and cron entry points
src/ministra/	Stalker Portal — isolated subsystem (BoundaryInterface)

---

Runtime model

Dependencies flow inward — modules may use core and domain, never the reverse.

public/index.php
    └── XC_Bootstrap::boot(BootContext::ADMIN)
            └── ServiceContainer (DI)
                    ├── EventDispatcher (PSR-14)
                    ├── ModuleLoader → loadAll() → bootAll()
                    └── Router → dispatch()

Domain classes receive the database via setDb() injection (called from bootstrap.php::wireDomainDatabase()). No global $db in the web request path.

---

Module system

Modules are isolated directories under src/modules/ with a module.json manifest and a class extending BaseModule. See Module System for the full reference.

src/modules/my-module/
├── module.json          # metadata
├── MyModuleModule.php   # extends BaseModule, namespace XcVm\Module\MyModule
└── ...

---

Bootstrap contexts

Four contexts control which subsystems initialize. See Bootstrap Contexts.

Context	Used for
BootContext::MINIMAL	Scripts needing only paths/config
BootContext::CLI	Cron jobs and CLI commands
BootContext::STREAM	Streaming endpoints
BootContext::ADMIN	Admin/reseller panel

---

Build variants (MAIN vs LB)

	MAIN	LB
Admin panel	✅	❌
Streaming	✅	✅
Module system	✅	subset

Controlled by ServerEnvironment enum and module.json environment field (main / lb / any).

---

Key extension points

Mechanism	How to use
PSR-14 events	EventDispatcher::listen() or #[ListensTo] attribute
Service decoration	$container->decorate('id', callable, priority)
Stream middleware	Implement StreamMiddlewareProviderInterface
Cron entries	Override getCronEntries() in module class
DB migrations	Implement MigratableInterface::getMigrations()

---

Contributor rules

1. Modules must not modify core files.
2. No eval, monkey patching, or runtime file replacement.
3. Any module can be disabled via config/modules.php without touching core.
4. Protected services (db, settings, config, auth) cannot be decorated.
5. Keep EN and RU docs in sync in the same commit.