Symfonicat

# Mental model

Symfonicat separates the public data plane from the administration control plane. Public traffic never depends on live CRUD queries: it builds an in-memory catalog from config/packages/symfonicat.yaml. The protected /core UI edits Doctrine rows, then automatically writes those rows back to the same YAML file.

# Quick start

The repository is self-contained: clone it, build the multi-stage image, synchronize discovered package data, load the YAML catalog, create a two-factor administrator, and unlock the core UI.

git clone https://github.com/symfonicat/core symfonicat
cd symfonicat
cp .env.example .env
docker compose up -d --build
docker exec -it php bin/console symfonicat:schema:update
docker exec php bin/console symfonicat:load
docker exec -it php bin/console symfonicat:admin:create <email>
touch symfonicat.lock

# Admin interface

The /core control plane is the operational center of Symfonicat. It is a server-rendered Bootstrap interface backed by Doctrine repositories and forms, giving administrators one place to configure the runtime without manually maintaining every relation in YAML. The dashboard opens on Domains and provides direct navigation to Domains, Subdomains, Endpoints, Parcels, Middleware, Applications, Environment, Files, schema synchronization, YAML dump/load, and logout.

What administrators configure

Schema and configuration workflow

The schema screen runs the same synchronization path as symfonicat:schema:update: it updates Doctrine metadata, reconciles tagged middleware, discovers package parcels and modules, and reports created, updated, or removed rows. The YAML controls expose explicit dump and load operations. Dumps exclude administrators, order tables by foreign-key dependency, and normalize JSON and booleans; loads validate tables and columns, delete children before parents, insert parents before children, reset sequences, and run inside a transaction.

# Docker and FrankenPHP stack

The Dockerfile starts from dunglas/frankenphp:builder-php8.4. Its base stage installs the C toolchain, Autoconf, Node 22, Composer, xcaddy, inotify, and the PHP extensions required by the application. It downloads FrankenPHP source because Symfonicat recompiles the server with project and vendor Go modules.

The php, npm, and messenger-worker services share named vendor and node_modules volumes. The entrypoint seeds /symfonicat/vendor from the Composer tree baked into the image, writes the Caddy TLS snippet from ECS certificate environment values when present, and otherwise uses internal TLS. Set SYMFONICAT_NATIVE_WATCH=1 to replace the normal server process with the native rebuild watcher.

# Public request lifecycle

1. PublicRuntimeSubscriberSkips /core/* and /application/*, resolves Domain and Subdomain from the host, validates signed /m/* module requests, and selects the most-specific matching Endpoint.
2. Normal Symfony routingRegular routes remain authoritative. Runtime catch-all routes use priority -1000 and require an explicit request attribute.
3. RuntimeRendererChooses the active entity, resolves an override or default Twig shell, issues a signed module context, and renders domain/subdomain/endpoint/application variables.
4. RuntimeMiddlewareRunnerBuilds a deduplicated PSR-15 chain from domain → subdomain → endpoint and converts between HttpFoundation and PSR-7.

Template precedence

templates/{domain,subdomain,endpoint}/overrides/{id}.html.twig
templates/{domain,subdomain,endpoint}/main.html.twig

For subdomains, the override id is the public affix. For domains and endpoints, it is the clean entity id. The renderer also exposes a signed request object used by frontend modules.

# Domains and reusable subdomains

A Domain id is always a bare hostname. DomainService finds the longest configured suffix, so both example.com and any host beneath it resolve to that domain. Public reads come from YAML; /core reads the database repository.

A Subdomain has an internal integer id, a public affix, and an optional Domain relation. Uniqueness is domain + affix, not affix alone. That means app.example.com and app.example.org can be distinct rows with different parcels, modules, middleware, and environment values while reusing the same public label.

# Endpoints

Endpoints turn paths into runtime targets. arguments is an ordered list of literals or * wildcards. catch allows trailing segments; an empty argument list with catch enabled acts as a wildcard for the current path. Endpoint rows can enforce a Domain or a Subdomain, then contribute their own parcel, modules, middleware, and env. Longer argument patterns are evaluated before shorter patterns so the most specific matching endpoint wins.

# Parcels and assets

A Parcel is the package-scoped frontend shell unit. Composer packages opt in with extra.symfonicat: true and place entries under assets/parcel/<name>/index.js. PackageDiscoveryService produces ids such as symfonicat/core/domainparcel; ParcelService synchronizes those paths and clears entity references when stale package parcels disappear.

Administrators choose which discovered Parcel implements each Domain, Subdomain, or Endpoint. This separates frontend implementation from tenant and route configuration: one Parcel can be reused by many runtime scopes, while any scope can switch to a different Parcel from the admin interface without changing its hostname, affix, or path rules.

# Modules and the hybrid package system

Modules are package-discovered features attachable to Domains, Subdomains, or Endpoints. The backend route exists only when its module is attached to the active runtime scope. This is enforced twice: signed request context validation in PublicRuntimeSubscriber, then attachment checks inside AbstractModuleController.

Runtime-aware services

A module is not limited to receiving JSON. Its controller inherits the core context services, and attributed action parameters are made callable during container compilation. Modules can therefore inspect the complete active request composition and respond differently for each tenant, path, application, or environment.

This service-based context model lets the same module implementation behave differently on separate Domains, on reused Subdomain affixes, at specific Endpoints, under different merged Env values, or inside a generated Application. Because these are normal Symfony services, modules can also request other typed application services in their #[Module] action signatures.

PHP module API

<?php

namespace Acme\Feature\Module;

use Symfonicat\Attribute\Module;
use Symfonicat\Attribute\ModuleRoute;
use Symfonicat\Controller\AbstractModuleController;
use Symfony\Component\HttpFoundation\Response;

#[ModuleRoute(path: '/m/acme/catalog')]
final class CatalogController extends AbstractModuleController
{
    #[Module(permission: 'PUBLIC_ACCESS')]
    public function product(): Response
    {
        $payload = $this->requestStack
            ?->getCurrentRequest()
            ?->attributes->get('module_json');

        return $this->json([
            'ok' => true,
            'productId' => $payload['productId'] ?? null,
            'domain' => $this->domainService->load()?->getTld(),
        ]);
    }

    #[Module]
    public function card(): Response
    {
        return $this->html('<article>Rendered by PHP</article>');
    }
}

#[ModuleRoute] targets a controller class and defaults to /m/<composer-package>. #[Module] targets a public action and defaults to PUBLIC_ACCESS. During container compilation, Symfonicat scans module actions and makes typed action dependencies callable.

JavaScript bridge

const mod = 'acme/catalog/main'

mod.log('module active')

// POST Brotli-compressed JSON to /m/acme/catalog/main/product
const product = await mod.json('product', {
    productId: 42,
})

// Request an HTML fragment from the same attached module.
const card = await mod.html('card', {
    productId: 42,
})

document.querySelector('#product-card').innerHTML = card

Caddy’s brotli_decompress Go handler expands every /m/* body before PHP. SymfonicatModuleSubscriber decodes JSON into the module_json request attribute. Empty JSON responses normalize to {}; HTML stays text.

One package, two back ends, one frontend

Symfonicat and Nymfonicat consume the same Composer-managed hybrid package. The shared package keeps browser code at its root and splits only the server implementation: Symfony/PHP code lives under src/, while Nymfonicat loads its Node.js counterpart from modules/.

symfonicat/analytics/
├── composer.json                 # extra.symfonicat: true
├── package.json                  # optional Node package metadata
├── assets/
│   ├── module/main/index.js     # one browser module for both runtimes
│   └── parcel/analyticsparcel/index.js
├── modules/main.js               # Nymfonicat Node.js backend
└── src/Module/AnalyticsModule.php # Symfonicat PHP backend

Hybrid lifecycle

1. Composer discovers the packageextra.symfonicat: true opts the package into Symfonicat and is also accepted by Nymfonicat discovery.
2. Each runtime registers its backendSymfonicat discovers attributed PHP actions; Nymfonicat resolves the package’s Node module path.
3. Both builds find the same assetsassets/module supplies browser features and assets/parcel supplies shell entries from the installed package.
4. Scopes select featuresAdministrators attach the module and choose the parcel for a Domain, Subdomain, or Endpoint.
5. The browser uses one contractThe same frontend sends the same action and payload; the current runtime dispatches locally to PHP or Node.js.

# PSR-15 middleware

Every service implementing Psr\Http\Server\MiddlewareInterface is automatically tagged symfonicat.middleware. The YAML catalog stores class-backed middleware rows and join tables for each scope.

1. Domain middlewareruns whenever a domain is active
2. Subdomain middlewareadds to subdomain and endpoint renders
3. Endpoint middlewareadds only for endpoint renders

The runner deduplicates by id/class, preserves scope order, passes Symfonicat request attributes into PSR-7, then converts the final PSR response back to HttpFoundation.

# Environment values

Environment keys are two-level names: an EnvParent such as colors plus an Env such as primary. Scope rows carry the actual string. EnvService recursively merges them and exposes the same grouped structure to Twig and window.env.

1. Parcelbase defaults for the selected shell
2. Domaintenant-wide overrides
3. Subdomainsubdomain parcel + scoped overrides
4. Endpointpath-context overrides
5. Applicationhighest priority in application context

{{ env('colors.primary') }}
<script>console.log(window.env.colors.primary)</script>

Infrastructure environment variables

Symfony loads .env, local overrides, and environment-specific files in increasing precedence; real process variables win. Compose rewrites database, Redis, Messenger, and Mercure addresses to their service names. The exported .env.example documents these runtime and AWS inputs:

# Symfony and runtime
APP_ENV APP_DEBUG APP_SECRET APP_SHARE_DIR SERVER_NAME DEFAULT_URI
DATABASE_URL REDIS_URL LOCK_DSN
MESSENGER_TRANSPORT_DSN MESSENGER_FAILED_TRANSPORT_DSN
MESSENGER_CONSUMER_NAME MESSENGER_WORKERS
MERCURE_URL MERCURE_PUBLIC_URL MERCURE_JWT_SECRET
ASSET_BASE_URL SYMFONY_TRUSTED_PROXIES SYMFONICAT_NATIVE_WATCH

# Local PostgreSQL
POSTGRES_DB POSTGRES_USER POSTGRES_PASSWORD

# Shared AWS configuration
AWS_REGION AWS_PROFILE

# ECR image build and push
AWS_ECR_REGION AWS_ECR_ACCOUNT_ID AWS_ECR_REPOSITORY AWS_ECR_TAG
AWS_ECR_CONTEXT AWS_ECR_DOCKERFILE AWS_ECR_BUILD_TARGET AWS_ECR_LOCAL_IMAGE

# ECS task and service
AWS_ECS_REGION AWS_ECS_CLUSTER_NAME AWS_ECS_SERVICE_NAME AWS_ECS_CONTAINER_NAME
AWS_ECS_IMAGE_URI AWS_ECS_WAIT_FOR_STABLE AWS_ECS_TASK_FAMILY AWS_ECS_LAUNCH_TYPE
AWS_ECS_CPU AWS_ECS_MEMORY AWS_ECS_CONTAINER_PORT AWS_ECS_DESIRED_COUNT
AWS_ECS_ASSIGN_PUBLIC_IP AWS_ECS_SUBNETS_JSON AWS_ECS_SECURITY_GROUPS_JSON
AWS_ECS_TARGET_GROUP_ARN AWS_ECS_EXECUTION_ROLE_ARN AWS_ECS_TASK_ROLE_ARN

# ACM and Route 53
AWS_CERT_REGION AWS_ECS_TLS_FULLCHAIN_B64 AWS_ECS_TLS_PRIVATE_KEY_B64
AWS_ROUTE53_REGION AWS_ROUTE53_RECORDS_JSON

# symfonicat.yaml

This file is both the deployable runtime catalog and the serialized admin configuration. AdminYaml introspects every symfonicat_* table except admins, orders tables by foreign-key dependency, normalizes JSON/booleans, and writes deterministic YAML. Loading runs in a transaction, deletes children before parents, inserts parents before children, validates tables/columns, and resets auto-increment sequences.

The catalog contains rows and join rows for parcels, domains, subdomains, endpoints, applications, env parents/keys/values, middleware, modules, and every attachment relation. Composer install runs symfonicat:purge; deployments then rebuild the schema and load clean configuration.

# Native C and Go system

Native code is a first-class package capability. Discovery scans three package layers: the application root, built-in core/, and every installed Composer package opted into Symfonicat. Each layer can ship traditional PHP C extensions and/or Go modules compiled into FrankenPHP.

native/
├── ext/
│   └── <php-extension>/
│       ├── config.m4
│       └── <extension>.c
└── go/
    └── <go-module>/
        ├── go.mod
        ├── *.go
        └── *.stub.php

core/native/{ext,go}/...
vendor/<vendor>/<package>/native/{ext,go}/...

C extension path

1. DiscoverNativeDiscoveryService finds child directories under every native/ext root using exact and glob package patterns.
2. Stagebin/native-build copies each directory into /usr/src/php/ext/<name>.
3. Configureconfig.m4 is inspected for PHP_ARG_ENABLE or PHP_ARG_WITH.
4. CompileAll discovered names are passed to docker-php-ext-install. Built-ins include the C remove_string function and the native module_routes scanner.

Go / FrankenPHP path

1. DiscoverDirectories under every native/go root must include Go source; module-backed entries expose a path in go.mod.
2. Generate PHP bridgeFiles containing export_php:function run through frankenphp extension-init, producing C headers, arginfo, stubs, and bridge code.
3. Resolve modulesgo mod tidy validates each module before build flags are assembled.
4. Compile serverxcaddy rebuilds FrankenPHP with CGO, Mercure, Vulcain, Caddy Brotli, project/vendor modules, and smaller no-database build tags.

Service proxy compilation

interface TextToolsInterface
{
    #[CompileNative]
    public function removeString(string $value, string $needle): string;
}

// NativeProxyCompilerPass detects the attribute and aliases the
// interface to Symfonicat\NativeProxy\Service\TextToolsNativeProxy.
// The proxy calls the compiled C extension function directly:
return \remove_string($value, $needle);

#[CompileNative] marks interface/service methods intended for native delegation. NativeProxyCompilerPass detects those methods, locates the matching Symfonicat\NativeProxy class, decorates the original service, and aliases supported App/Native/Symfonicat interfaces to the proxy.

Development watcher

With SYMFONICAT_NATIVE_WATCH=1, bin/native-watch snapshots root/core/vendor native files, prefers recursive inotify, falls back to polling, recompiles on change, and restarts FrankenPHP only after a successful native build. It records backend, PID, snapshot, timestamp, and last changed path in a sentinel file.

# Applications and Electron

An Application selects a Domain, Subdomain, or Endpoint context. Requests carrying the application id expose the entity in Twig and window.application; its environment rows override endpoint values.

symfonicat:application:build clears generated output and creates applications/<application.id>/main.js, package.json, and README.md. It resolves templates/application/overrides/<id>.js.twig before the default template, builds an HTTPS URL from domain + subdomain + endpoint arguments, and configures Electron Builder.

# Console command map

# AWS deployment

The repository includes an end-to-end container path rather than generic cloud notes.

Defaults are 512 CPU units, 1024 MiB, one public Fargate task on port 443, with default-VPC discovery and an auto-created security group. The entrypoint converts exported certificate environment variables into Caddy-readable files.

# Complete core/src atlas

All 129 files are indexed below. Each group corresponds to an architectural responsibility; every filename links directly to its implementation.

# Testing and the rest of the README

docker exec -it php ./bin/phpunit

The test environment lowers password-hashing cost, uses dedicated cache/Doctrine/routing configuration, and the repository includes unit and integration coverage for runtime, admin, modules, native discovery, configuration, templates, middleware, and commands.

Picture of @dunglas at the zoo