Architecture

The master diagrams of the Flyokai framework, in one place.

Application types

Type	Purpose	Bootstraps loaded
Setup	First-install / upgrade	Base + Setup
Cli	Console commands	Base + Cli
Web	Plain HTTP server	Base + Web
Worker	Worker process — extends Web with cluster IPC	Base + Web + Worker
Cluster	Coordinator	Base + Cluster
Task	One-off background tasks	Base + Task

Bootstrap lifecycle

Module composer.json autoload calls Registry::addModule()
   │
   ▼
RootBootstrap(ApplicationType)
   │
   ├── Init phase    — every module's init() registers DI config files
   ├── Build phase   — Amp Injector Application built from merged definitions
   └── Bootstrap     — every module's bootstrap() runs against the live container

DI config files run during init; the container does not yet exist. Use only RootBootstrap methods at that point.

HTTP flow

AMPHP SocketHttpServer
   ▼
Router (method + URI match via fast-route)
   ▼
HandlerGuard (Authorization::isAllowed for ProtectedHandlers, skipped for GuestHandlers)
   ▼
RequestHandler::handleRequest()
   ▼
Response (typically JSON)

• flyokai/application provides the server lifecycle and the router builder.
• flyokai/oauth-server provides HandlerGuard\Authorization for Bearer-token validation.

Data-service flow

Client
   ▼
Socket connect → SocketDataServer accepts → ClientHandlerImpl created
   ▼
First message MUST be AccessToken — OAuth handshake
   ▼
StreamChannel + Dispatcher initialised
   ▼
Dispatcher loop: receive → Router → Middleware → Handler → Response
   ▼
Loop until client disconnects or TimeoutQueue fires

• flyokai/data-service provides the socket server, router, and middleware.
• flyokai/data-service-message provides the built-in request/response DTOs.
• flyokai/amp-channel-dispatcher provides the underlying request/response dispatcher.

Database layer

Application Config
   ▼
ConnectionPool (interface) — Amp / AsyncPdo / AsyncMysqli / TwoLevel
   ▼
Laminas\Db\Adapter\Adapter
   ▼
Async Driver (suspends fibers, never blocks the loop)

The default in Flyokai is AsyncMysqliConnectionPool. Switch via the ConnectionPool alias in your project's diconfig.php.

Data pipeline

DataSource (Array / Iterator / Queue)
   ▼
Processor (concurrency + bufferSize)
   ▼  ProcessorComposition chains stages
Processor
   ▼  Optionally BatchProcessor groups
   ▼  Optionally MultiCastProcessor fans out
Bulk DB ops (InsertOnDuplicate, ID resolvers)

• flyokai/amp-data-pipeline provides the primitives.
• flyokai/laminas-db-bulk-update provides the bulk DB writes.
• flyokai/indexer uses pipelines for full reindex.

DI architecture (one-screen view)

diconfig.php files (one per module per app type)
   ▼  merged via DiConfig::merge()
Definitions ⨯ Arguments
   ▼
Injector (root Weaver = any(automaticTypes, runtimeTypes))
   ▼
Application (immutable; holds Container + Injector)
   ▼
container->get(id)

• flyokai/amphp-injector is the engine.
• flyokai/application produces the diconfig stack.
• flyokai/composition orders modules + DB setup steps.
• See dependency-injection.md for the detailed file format.

Schema architecture

Solid DTOs tagged with #[Table]
   ▼
SchemaDiscovery (walks Registry::modules() + PSR-4 roots)
   ▼
SchemaModel (declared)
                   ┐
INFORMATION_SCHEMA ┴─► SchemaIntrospector ──► SchemaModel (existing)
                                                    │
                          ◄────  SchemaDiffer  ─────┘
                                       │
                                       ▼
                                 SchemaPlan (TableDiff[])
                                       │
                                       ▼
                          SchemaApplier (two passes: structure → FKs)
                                       │
                                       ▼
                              MySQL ALTER / CREATE

• flyokai/db-schema is the engine.
• The Setup\Step\ApplySchema step is Repeatable and runs on every setup:install / setup:upgrade.
• Drops are gated behind FLYOK_DB_SCHEMA_ALLOW_DESTRUCTIVE=1.

Search-criteria architecture

raw JSON
   ▼  CriteriaJsonNormalizer
canonical array
   ▼  CriteriaMapper
typed SearchCriteria
   ▼  FieldCollector → BaseColumnValidator → JoinResolver
fields validated, joins resolved
   ▼  SelectCompiler
Laminas\Db\Sql\Select  →  bound, executed, mapped to Solid DTOs

flyokai/search-criteria plugs into any repository via CriteriaRepositoryTrait.