EngineCore

AI generates code fast. That is the problem.

Without structure, AI fills every gap with its own judgment. Logic leaks into transport. Side effects hide in business logic. The same decision gets made in five different places.

EngineCore enforces a boundary between decisions and execution — so AI has no room to improvise where it matters.

Built and tested in real production software. AI wrote 100% of the code.

What this proves

• Same input → same output. Always.
• Runtime failures do not affect engine decisions.
• Flows can be replayed from saved event logs.
• Examples are runnable, not conceptual.

The problem

Traditional architectures rely on developer discipline.

That works when a human writes the code. A human understands context, remembers conventions, asks when unsure.

AI does not.

AI does what the structure allows. If the structure is loose, the result is inconsistent — and AI makes it inconsistent faster than any developer ever could.

How it works

EngineCore separates decisions from execution across four layers:

Server → Engine → Feature → Runtime

Layer	Responsibility
Server	validate request, inject metadata, dispatch command
Engine	route command to feature — no logic, no IO
Feature	all business logic — pure, deterministic, no IO
Runtime	all external interaction — IO, persistence, side effects

One place where decisions are made. One place where IO happens. No exceptions.

Key principles

Decisions are deterministic. Execution is not.

Business logic lives only in Features. No logic in server, runtime, transport, or persistence. One place. Always.

IO is isolated. All external interaction goes through Runtime. No database calls in features. No hidden side effects.

Deterministic core. Features are pure functions — same input, same result, always. No randomness, no time access, no async.

Explicit side effects. Features do not execute IO. They return effects:

{
  stateChanges,
  effects: [
    { type: 'SET_STATE', ... },
    { type: 'EMIT_EVENT', ... },
    { type: 'SCHEDULE_TASK', ... }
  ]
}

Runtime executes those effects. Features never do.

Structure over discipline. EngineCore enforces constraints, not conventions. Fewer decisions. Fewer failure paths. Consistent outcomes.

Runtime

Runtime is not a single block. It is split by technical responsibility:

Module	Responsibility
Command Pipeline	receive command, load state, call engine, route result
Persistence	state snapshot, event/outbox, transactions
Idempotency	key lookup, duplicate prevention, replay-safe writes
Concurrency	optimistic version check, conflict handling
Effect Dispatch	route effects to handlers — execute, not reinterpret
Scheduling	delayed work, retries, scheduled commands
Transport	HTTP callbacks, webhooks, email, push, websocket
Observability	logging, tracing, metrics, correlationId — throughout

Domain can grow freely. Runtime stays bounded.

Example flow

1. Server receives request
2. Command enters Command Pipeline
3. Idempotency + concurrency checks
4. Engine routes command to Feature
5. Feature executes — pure, no IO
6. Feature returns state changes + effects
7. Persistence stores state + outbox atomically
8. Effect Dispatch executes effects
9. Observability runs throughout

Quick start

1. Copy the foundation files into your project:

   • ENGINECORE_CORE.md
   • AI_WORKFLOW.md
   • FRONTEND_ENGINECORE.md

2. In your project, define:

   • PROJECT_RULES.md
   • DOMAIN_MODEL.md
   • ARCHITECTURE.md
   • any additional documents the project needs (AUTH.md, INTEGRATIONS.md, etc.)

3. Follow AI_WORKFLOW.md to start coding.

4. See example/add-product/ for a minimal working reference.

5. See example/deterministic-agent/ for a replay proof.

6. See example/project-docs/ for document templates.

What EngineCore is not

EngineCore is not a framework, not a library, and not tied to any language or stack. It is a structural model. You implement it in whatever stack you use.

When to use

EngineCore fits well when systems grow beyond simple CRUD, when consistency matters, when side effects become complex, or when AI is used for code generation. It is overkill for simple scripts, small CRUD apps, and one-off integrations.

Philosophy

Bad code is often allowed by structure, not caused by developers.

Fix the structure, and the code follows.

This applies to AI-generated code too — arguably more so, because AI has no intuition about what should be done. It only knows what is allowed.

Status

This project is under active development and being tested in real production software. The goal is to validate whether strict structure can improve AI-generated code quality, reduce architectural drift over time, and make systems easier to reason about.

Contributing

Discussion, criticism, and real-world feedback are welcome. The most valuable input is where this model breaks, where it becomes too rigid, and where it adds unnecessary complexity.

If you have built AI-assisted systems and hit a wall — this is the place to compare notes.