Cephalon App Models

Editable diagram: docs/cephalon-app-models.drawio

Why this exists

Apps that attach to the Cephalon engine should be able to choose a project shape intentionally. But the choices need to be modeled correctly.

The original candidate list mixes different kinds of decisions:

Modular Architecture: application composition style
Microservice Architecture: deployment topology
Vertical Slice Architecture: feature organization style
Shared Foundation Pattern: shared platform/base layer
Strategy Pattern: internal behavior extension pattern
REST API, JsonRpc, Grpc, GraphQL, SSE, WebSocket: transport surface choices

Cephalon should not treat all of these as equal top-level architecture choices. Instead, it should define an App Model made from multiple dimensions.

App model dimensions

1. Composition model

How the application is assembled.

Supported direction:

Modular
Plugin-ready Modular later

2. Deployment topology

How the application is deployed.

Supported direction:

SingleHost
Microservice
MicroserviceSuite

3. Feature organization

How code is laid out inside the app or module.

Supported direction:

VerticalSlice
ModuleFirst

4. Shared foundation

The common runtime, contracts, policies, diagnostics, and conventions all apps inherit from the engine.

Supported direction:

always on for Cephalon apps

5. Transport surface

How the app exposes commands, queries, events, or streams to the outside world.

Supported direction:

RestApi
JsonRpc
Grpc
GraphQL
ServerSentEvents
WebSocket

Multiple transports may be enabled together when the host supports them. Transport selection and host adapter registration must stay aligned. Some transports, such as Grpc, may expose both unary and streaming interaction styles inside the same transport choice. On ASP.NET Core hosts, RestApi should expose OpenAPI and Scalar as the REST documentation surface. Cephalon keeps REST document customization in OpenAPI transformers inside the ASP.NET Core host package.

6. Behavioral extension

How variable behavior is swapped or selected inside a feature/module.

Supported direction:

optional strategy slots
policy-driven selection later

7. Technology profile

How future-facing workload capabilities are layered onto the app model without turning every new technology into a new blueprint.

Supported direction:

AgenticWorkloads
CellBasedArchitecture
EventDrivenIntegration
KnowledgeRetrieval
RealtimeExperience
EdgeNativeDelivery
IdentityAccess
MultiTenancy
HybridCloudRuntime
ServiceMeshIntegration
ServerlessHosting

Technology profiles should carry workload guidance, validation rules, and scaffold conventions for emerging stacks such as AI orchestration, event-driven integration, retrieval-heavy systems, realtime experiences, or edge-aware deployments. That same layer now also carries CellBasedArchitecture, where cell boundaries stay a technology/runtime concern instead of becoming a new blueprint or deployment shape. They may also be supplied by packages or project code when a team needs to model a future stack that is not part of the built-in catalog yet.

Recommended interpretation of the candidate choices

User term	What it really is in Cephalon
Modular Architecture	Primary composition model
Microservice Architecture	Deployment topology
Vertical Slice Architecture	Feature organization style
Shared Foundation Pattern	Mandatory engine foundation
Strategy Pattern	Internal extension mechanism
Agentic / Event-Driven / Knowledge / Realtime / Edge profiles	Technology profile
REST API / JsonRpc / Grpc / GraphQL / SSE / WebSocket	Transport surface

Predefined Cephalon blueprints

Cephalon should expose a small set of predefined blueprints instead of forcing users to compose every axis manually.

Developers should also be able to add supporting design patterns on top of a blueprint instead of treating them as competing top-level architectures.

1. `ModularMonolith`

Default blueprint for most new products.

Shape:

single host
modular composition
module-first structure
shared engine foundation
optional strategies inside modules

Use when:

the product is new
domain boundaries matter
independent deployment is not needed yet

2. `ModularVerticalSlice`

Best default for product teams building features quickly.

Shape:

single host
modular composition
vertical-slice organization inside each module
shared engine foundation
optional strategies per slice

Use when:

the team wants strong feature ownership
HTTP/API/application logic should stay close together
the product may later split by domain

3. `Microservice`

A single service built on Cephalon engine conventions.

Shape:

one independently deployable service
modular composition inside the service
usually vertical slices inside modules
shared engine foundation

Use when:

service boundaries are already clear
separate deployment/scale/security boundaries are needed

4. `MicroserviceSuite`

A higher-level solution template, not just one app.

Shape:

multiple Cephalon services composed from the existing Microservice blueprint
a shared foundation project for suite-level contracts and conventions
a shared governance package for suite-level policy and additive gateway/control-plane guidance
optional gateway/control-plane pieces can layer on later without changing the suite contract

Use when:

multiple services are intentionally designed together
platform governance and conventions matter across services
teams want a reference sample that keeps each service on the shipped Microservice host wiring while sharing one suite foundation

Engine contract today

The engine now models these choices as first-class runtime objects, not as plain text labels.

Current shipped shape:

AppBlueprint defines the built-in project shape and required baseline patterns
SuiteBlueprint defines the built-in suite-level project shape when Cephalon needs a coordinated multi-service blueprint
AppProfile captures the selected blueprint, patterns, technologies, transports, and scaffold plan
ScaffoldPlan captures how that blueprint should turn into projects, folders, conventions, and package hints
SuiteScaffoldPlan and SuiteScaffoldService now capture the solution-level shape for shared projects plus per-service slots without changing the current app-level runtime contract
built-in scaffold plans live under Cephalon.Engine.AppModel.Scaffolding, and built-in suite blueprints now live under Cephalon.Engine.AppModel

Simplified contract:

1
public sealed class AppProfile
2
{
3
    public string BlueprintId { get; }
4
    public IReadOnlyList<PatternDescriptor> Patterns { get; }
5
    public ScaffoldPlan? Scaffold { get; }
6
    public IReadOnlyList<TechnologyDescriptor> Technologies { get; }
7
    public IReadOnlyList<TransportDescriptor> Transports { get; }
8
    public DataSelection Data { get; }
9
    public DatabaseTopologySelection Databases { get; }
10
    public IdentitySelection Identity { get; }
11
    public TenancySelection Tenancy { get; }
12
    public AuditSelection Audit { get; }
13
    public MessagingSelection Messaging { get; }
14
    public ResilienceSelection Resilience { get; }
15
}

The current runtime still resolves app-level AppProfile objects only. The suite layer is now modeled separately through SuiteBlueprint, with the built-in MicroserviceSuite blueprint composing repeatable service slots from the shipped Microservice scaffold contract instead of redefining service internals at the suite layer. The resolved app profile now also carries structured configuration selections for Data, Databases, Identity, Tenancy, Audit, Messaging, and Resilience. The new Databases block is the engine-owned physical-topology baseline for shared runtime tuning plus the first named roles (Write, Read, Outbox, History) and nested migration policy. Audit.History now also carries nested Export plus Retention inputs so the durable audit-history read and export surfaces stay visible in the same app-model contract. Resilience remains the contract-first phase-11 baseline for Retry, Timeout, CircuitBreaker, Bulkhead, and RateLimiting policy intent through both /engine/app-model and /engine/resilience, while the shipped behavior-execution follow-through now also carries additive BehaviorExecutionOverrides plus effective retry, timeout, circuit-breaker, and bulkhead answers through /engine/behavior-resilience and RuntimeIntrospectionSnapshot.BehaviorResiliencePolicies. Those overrides can now target behavior ids, transport ids, or both, and the runtime resolves them with behavior+transport precedence over behavior-only, transport-only, and default answers. The behavior contract layer now also lets authors declare replay safety explicitly through BehaviorIdempotencyAttribute, and IBehaviorResilienceRuntimeCatalog.Resolve(...) can reflect the resulting retry eligibility as eligible, ineligible, or unknown per behavior. Automatic retry execution now runs through the shared behavior pipeline with configured attempts, backoff, delays, and jitter only when the effective policy requests retry and the classifier sees an explicitly idempotent transient failure; non-idempotent or unknown behaviors still fail without automatic replay. Circuit breaker continues to participate in the same shared dispatch pipeline and publishes live runtime metadata such as circuit state and retry-after timing. AppProfile.Databases remains the requested topology selection, while the resolved operator-facing role truth now also lives beside it through IDatabaseRoleCatalog, /engine/database-roles, and RuntimeIntrospectionSnapshot.DatabaseRoles. The resolved operator-facing migration truth now lives beside it through IDatabaseMigrationCatalog, /engine/database-migrations, and RuntimeIntrospectionSnapshot.DatabaseMigrations. Legacy display-name aliases still resolve for compatibility, but the shipped starter and template surfaces now emit canonical kebab-case ids plus those structured sections by default.

The runtime should support configuration-driven blueprint, pattern, technology, and transport selection, for example:

1
{
2
  "Engine": {
3
    "Blueprint": "modular-vertical-slice",
4
    "Patterns": ["strategy-pattern", "pipeline-pattern", "cqrs"],
5
    "Technologies": ["event-driven-integration", "identity-access"],
6
    "Transports": ["rest-api"],
7
    "Data": {
8
      "ReadWriteSplit": true,
9
      "Ids": {
10
        "Generator": "Sfid"
11
      }
12
    },
13
    "Identity": {
14
      "Enabled": true,
15
      "AuthorizationModes": ["RBAC", "ABAC", "Policy"]
16
    },
17
    "Tenancy": {
18
      "Enabled": false
19
    },
20
    "Audit": {
21
      "Enabled": true,
22
      "History": {
23
        "Enabled": true,
24
        "Provider": "entity-framework",
25
        "DatabaseRole": "history",
26
        "Export": {
27
          "Enabled": true,
28
          "MaxEntries": 1000
29
        },
30
        "Retention": {
31
          "Enabled": true,
32
          "MaxAgeDays": 90,
33
          "DeleteBatchSize": 250,
34
          "ApplyOnStartup": true
35
        }
36
      }
37
    },
38
    "Messaging": {
39
      "Provider": "Wolverine"
40
    },
41
    "Resilience": {
42
      "Retry": {
43
        "Enabled": true,
44
        "MaxAttempts": 3,
45
        "Backoff": "Exponential",
46
        "BaseDelayMilliseconds": 2000,
47
        "UseJitter": true
48
      },
49
      "Timeout": {
50
        "Enabled": true,
51
        "TotalTimeoutSeconds": 30,
52
        "AttemptTimeoutSeconds": 10
53
      },
54
      "CircuitBreaker": {
55
        "Enabled": true,
56
        "FailureRatio": 0.1,
57
        "MinimumThroughput": 100,
58
        "SamplingDurationSeconds": 30,
59
        "BreakDurationSeconds": 5
60
      },
61
      "Bulkhead": {
62
        "Enabled": true,
63
        "MaxConcurrentExecutions": 64,
64
        "MaxQueuedActions": 128
65
      },
66
      "RateLimiting": {
67
        "Enabled": true,
68
        "Algorithm": "SlidingWindow",
69
        "PermitLimit": 200,
70
        "QueueLimit": 20,
71
        "WindowSeconds": 60,
72
        "SegmentsPerWindow": 4
73
      }
74
    }
75
  }
76
}

That gives developers a controlled way to mix architecture choices, design patterns, future-facing technology profiles, and delivery protocols without losing validation or runtime introspection.

Technology profiles are intentionally lighter than blueprints. They should add workload semantics, dependency hints, validation rules, and scaffold conventions without forcing an entirely new project shape. They should also be additive by default: built-ins come from the engine, packages can contribute more through ITechnologyContributor, and projects can register their own descriptors without rewriting the blueprint catalog. When a profile needs reusable runtime services, Cephalon prefers a companion package such as Cephalon.Agentics, Cephalon.Eventing, Cephalon.Retrieval, or Cephalon.Edge over expanding the engine core directly.

If a transport is implemented by a companion host package, the app must both select it in Engine:Transports and register the matching adapter in startup.

Code can still layer on top when a host needs to override or add behavior:

1
builder.AddCephalon(engine =>
2
{
3
    engine.AddPattern(BuiltInPatterns.MediatorPattern);
4
    engine.RegisterTechnology(new TechnologyDescriptor(
5
        id: "digital-twin-orchestration",
6
        displayName: "Digital Twin Orchestration",
7
        description: "Project-specific catalog entry contributed in startup.",
8
        kind: TechnologyKind.Experience));
9
    engine.AddTechnology(new TechnologyDescriptor(
10
        id: "custom-digital-twin",
11
        displayName: "Custom Digital Twin",
12
        description: "Project-specific future technology profile.",
13
        kind: TechnologyKind.Experience));
14
});

The same override model now applies to language resources. Installed modules can contribute language packs through ILocalizedResourceContributor, hosts can declare baseline localization in Engine:Localization, apps can add project-specific cultures with engine.AddLanguageResources(...), and projects can still replace the localization contract through DI when they need complete ownership of how human-language text is resolved.

The same override model now applies to future-tech choices as well. Built-in technology profiles come from Cephalon.Engine.Technologies.BuiltInTechnologies, while a project can add its own descriptors through engine.AddTechnology(...) when it needs to model a domain-specific runtime such as digital twins, robotics, spatial computing, or custom inference pipelines. Installed modules and package-loaded assemblies can also contribute technology profiles through ITechnologyContributor, which then become visible through /engine/technology-catalog and selectable through Engine:Technologies. Installed modules can also react to active selections through ITechnologyServiceContributor and ITechnologyCapabilityContributor, which makes future-tech profiles useful at runtime instead of only decorative in metadata.

Scaffold plan contract

Each built-in blueprint now carries a scaffold plan that can drive future generators and templates.

The scaffold plan includes:

Projects: named project templates, roles, scopes, dependencies, and recommended Cephalon package references
Folders: module or feature folder conventions scoped to the owning project
Conventions: startup and composition rules that keep generated hosts thin
Metadata: small shape hints such as organization style or deployment topology

Current placeholder tokens in scaffold templates:

{AppName}
{ModuleName}
{FeatureName}

Transport selection can enrich the scaffold plan further. For example, selecting JsonRpc, Grpc, or GraphQL adds adapter package hints and host registration conventions to the host project plan. Technology selection can enrich it too by appending workload guidance and future-ready conventions without forcing a whole new blueprint.

The same scaffold plan is visible:

in the runtime manifest under appProfile.scaffold
through GET /engine/scaffold

The same scaffold plan now also drives Cephalon.Scaffolding, which can render:

a .slnx solution file
concrete .csproj files
starter Program.cs, split Configurations/Add*.json host settings, and standard appsettings*.json override files
module stubs and contracts
placeholder feature folders for blueprint-specific slice structures

Cephalon.Cli now sits on top of that generator so developers can pick blueprints, patterns, technologies, transports, modules, and features from one command without redefining the app model rules.

Cephalon.TemplatePack is now the lighter dotnet new surface over the shipped blueprint family:

cephalon-monolith -> ModularMonolith
cephalon-slice -> ModularVerticalSlice
cephalon-microservice -> Microservice

That means Cephalon now has two generation surfaces with different tradeoffs:

Cephalon.TemplatePack for fast starter installs
Cephalon.Cli for richer blueprint, transport, pattern, module, and feature composition

Module authoring now has a parallel starter path too:

cephalon-module for host-agnostic package starters
cephalon-rest-module for REST-capable package starters

What Cephalon now scaffolds from a blueprint

solution/project layout
host type and startup conventions
module structure
feature folder conventions
diagnostics and manifest defaults
test project layout
sample modules/slices

`ModularMonolith` scaffold shape

host project: src/{AppName}.Host
foundation project: src/{AppName}.Foundation
repeatable module project: src/{AppName}.Modules.{ModuleName}
test project: tests/{AppName}.Tests
module folders: Application, Domain, Infrastructure, Endpoints, Strategies

`ModularVerticalSlice` scaffold shape

host project: src/{AppName}.Host
foundation project: src/{AppName}.Foundation
repeatable module project: src/{AppName}.Modules.{ModuleName}
test project: tests/{AppName}.Tests
slice folders: Features/{FeatureName}/Commands, Queries, Endpoints, Contracts, Policies, Strategies

`Microservice` scaffold shape

service host project: src/{AppName}.Service
foundation project: src/{AppName}.Foundation
contracts project: src/{AppName}.Contracts
repeatable module project: src/{AppName}.Modules.{ModuleName}
test project: tests/{AppName}.Service.Tests
slice folders: Features/{FeatureName}/Api, Application, Contracts, Policies

Proposed first blueprint set

ModularMonolith
ModularVerticalSlice
Microservice
MicroserviceSuite

MicroserviceSuite is now available as a suite-level blueprint that composes repeatable service slots from the shipped Microservice scaffold contract. The reference sample lives under samples/Cephalon.Sample.MicroserviceSuite, now includes a shared governance package, and documents additive optional gateway/control-plane guidance without turning those layers into required suite-contract pieces.

Suggested configuration

Use the Engine section as the primary source of truth for blueprint, pattern, technology, and transport selection.

1
{
2
  "Engine": {
3
    "Blueprint": "modular-vertical-slice",
4
    "Patterns": ["strategy-pattern", "pipeline-pattern"],
5
    "Technologies": ["identity-access"],
6
    "Transports": ["rest-api"],
7
    "Data": {
8
      "Ids": {
9
        "Generator": "Sfid"
10
      }
11
    },
12
    "Identity": {
13
      "Enabled": true,
14
      "AuthorizationModes": ["RBAC", "ABAC", "Policy"]
15
    },
16
    "Tenancy": {
17
      "Enabled": false
18
    },
19
    "Audit": {
20
      "Enabled": true,
21
      "History": {
22
        "Enabled": true,
23
        "Provider": "entity-framework",
24
        "DatabaseRole": "history",
25
        "Export": {
26
          "Enabled": true,
27
          "MaxEntries": 1000
28
        },
29
        "Retention": {
30
          "Enabled": true,
31
          "MaxAgeDays": 90,
32
          "DeleteBatchSize": 250,
33
          "ApplyOnStartup": true
34
        }
35
      }
36
    },
37
    "Messaging": {},
38
    "Resilience": {
39
      "Retry": {
40
        "Enabled": true
41
      }
42
    }
43
  }
44
}

Decision rules

if the user says Modular, choose ModularMonolith by default
if the user says Vertical Slice, choose ModularVerticalSlice by default
if the user says Microservice, generate a Cephalon-powered service, not a distributed suite automatically
Shared Foundation is not optional for Cephalon apps
Strategy Pattern should appear as generated extension points, not as the whole project shape
technology profiles should carry future-facing workload guidance instead of turning every new tech stack into a blueprint
transport selection is explicit and may include more than one protocol when the chosen host supports it

Recommendation for Cephalon v1

For v1, support:

ModularMonolith
ModularVerticalSlice
Microservice
MicroserviceSuite

That is enough to prove the model cleanly across single-app and multi-service shapes without pretending every pattern is a first-class runtime concern on day one.

Cephalon App Models

Why this exists

App model dimensions

1. Composition model

2. Deployment topology

3. Feature organization

4. Shared foundation

5. Transport surface

6. Behavioral extension

7. Technology profile

Recommended interpretation of the candidate choices

Predefined Cephalon blueprints

1. ModularMonolith

2. ModularVerticalSlice

3. Microservice

4. MicroserviceSuite

Engine contract today

Scaffold plan contract

What Cephalon now scaffolds from a blueprint

ModularMonolith scaffold shape

ModularVerticalSlice scaffold shape

Microservice scaffold shape

Proposed first blueprint set

Suggested configuration

Decision rules

Recommendation for Cephalon v1

1. `ModularMonolith`

2. `ModularVerticalSlice`

3. `Microservice`

4. `MicroserviceSuite`

`ModularMonolith` scaffold shape

`ModularVerticalSlice` scaffold shape

`Microservice` scaffold shape