SynthKernel

A novel architecture for modular monolith development in TypeScript. It leverages the power of type orchestration and runtime dynamics to deliver a type-safe, scalable, and highly modular software paradigm.

GitHub Whitepaper

Abstract

The modular monolith is not a new concept. For decades, developers have sought the balance between the simplicity of a monolith and the maintainability of microservices. Yet, the implementation of this pattern often falters under the weight of "God Objects," manual registry maintenance, and configuration drift.

SynthKernel does not invent the modular monolith. Instead, it proposes a novel architectural paradigm for structuring one. By leveraging advanced TypeScript generics, extreme Inversion of Control, and a strict Loader-Module separation, SynthKernel ensures that modularity is enforced by the type system itself. This article explores the architecture's unique approach to type orchestration, its AI-native design philosophy, and how it eliminates the friction traditionally associated with modular development.

→ Explore the GitHub Repository

The Architectural Friction Problem

While the benefits of modular design are well-documented, the mechanics of implementation remain painful. Traditional approaches typically suffer from flaws below:

1. The God Object Loader: The central loader accumulates business logic, becoming a bottleneck for maintenance.
2. Manual Registry Drift: Developers must manually update interface definitions when adding new modules, leading to mismatches between code and types.
3. Weak Encapsulation: Modules import each other directly, creating tight coupling that defeats the purpose of modularity.
4. Module Entanglement: Even with modular design, the complexity of inter-modular dependencies and inheritance can also become unmanageable.

SynthKernel addresses these issues not by changing the goal (modular monolith), but by reinventing the structure. It shifts the center of gravity from the Loader to the Modules, using the type system to automate what was previously manual labor.

What Makes SynthKernel Novel?

SynthKernel is a low-level system design approach that pushes the philosophy of Inversion of Control (IoC) to its extremum. Its novelty lies in three core architectural decisions:

1. Modules Are the Center

In most frameworks, the Loader (or Framework Core) provides the APIs. In SynthKernel, Modules are the actual center of the entire application. Modules define APIs, execute real logic, and wire themselves via dependency injection. The Loader acts solely as a lifecycle manager and a facade. It contains no business logic.

2. Type Orchestration

SynthKernel uses advanced TypeScript generics to automatically merge module interfaces into the Loader's type definition.

For example, ff a module contributes a method dispatch(), the Loader's type automatically gains dispatch(). If the module is removed, the method vanishes from the type, triggering a compile-time error if still referenced. This can eliminate drift with type system becoming the single source of truth.

3. Runtime Augmentation

Modules physically attach their methods to the Loader instance at runtime via a controlled augment() mechanism. This ensures that the static type safety matches the runtime behavior, a rare achievement in dynamic languages.

Core Architecture Overview

A SynthKernel implementation consists of a central Loader and flat Modules, structured strictly to ensure clarity and AI compatibility.

Loader

• Manages module lifecycles (Start, Dispose, Restart)
• Orchestrates types (via Generics)
• Acts as facade (Augmented by modules)
• Contains NO business logic

Module

• Interop via dependency injection
• augment loader
• declare types
• executes business logic

Sub-Loader

• simultaneously a module and a loader
• achieves logic that cannot be handled by a single loader
• handles inter-hierarchy communication

Module

Module

Module

Module

Module

Consumer Code

Interacts only with the loader.

Components

• index.ts (Loader): The entry point. Defines base options and lifecycle hooks.
• BaseModule.ts: The abstract base class all modules extend.
• types.ts: Core utility types for orchestration (Orchestratable).
• [ModuleName].ts: Self-contained logic units that augment the Loader.

The AI-Native Advantage

SynthKernel is designed not just for humans, but for agentic coding. AI models perform best when constrained by strict guidelines and patterns (similar to how they excel with React or Vue). SynthKernel imposes strict conventions in file names (index.ts, BaseModule.ts), class structures, and naming rules are standardized. It also enforces the clear separation between Loader (lifecycle) and Modules (logic), which reduces the risk of AI entangling themselves as well as the codebase into a spaghetti.

Agent Skill

SynthKernel provides an official Agent Skill to assist in scaffolding and maintenance. This ensures that AI-generated code adheres to the architecture's strict standards.

Install the Skill:

npx skills add hesprs/synthkernel

This allows coding agents to automatically generate modules, split bloated logic, and maintain the project structure without human intervention.

When to Use SynthKernel

SynthKernel is a powerful tool, but it is not a silver bullet. It is best suited for specific contexts where structure and type safety are paramount.

✅ Ideal Use Cases

• Backend Services: Complex business logic requiring clear modular boundaries.
• CLI Applications: Modular commands that need shared configuration.
• Automation Engines: Pluggable workflows with strict lifecycle management.
• Canvas Rendering Systems: Composable layers with shared state.
• Large Modular Monoliths: Projects exceeding 5,000 LOC where structure is critical.

❌ When Not to Use

• Frontend UI: React, Vue, and Svelte have their own established conventions.
• Simple Scripts: For projects under 200 LOC, a classical monolith is more convenient.
• Fixed Architecture Projects: If you cannot refactor existing conventions, SynthKernel may not fit.

Getting Started

SynthKernel is design philosophy, not a library or software. You can try to kick off a sample project that experiment with SynthKernel.

Prerequisites

• TypeScript 5.0+
• A JavaScript Runtime (including browsers)
• A DI Library

Resources

• README: Walk you though what SynthKernel is and how to setup skill and whitepaper.
• Whitepaper: Read the executable TypeScript whitepaper in Jupyter Notebook format.
• Example: Explore the PolisAlert demo project.

Research & Licensing

SynthKernel is an experimental, open-source research project maintained by Hēsperus. It is licensed to encourage both adoption and collaboration.

• Architecture Whitepaper & README: CC BY-SA 4.0
• Agent Skill: MIT License
• Copyright: © 2026 Hesprs (Hēsperus)